CLI Reference

上一页 下一页

Run with python main.py [arguments]. Before argument parsing, an ASCII banner is printed.

Help and Version

python main.py --help
python main.py --version

--version outputs: Z-Sans Asset Breeding Engine v0.0.7.

All Arguments

Argument Type Default Description
-c, --config <path> string breeding-config.yaml Path to the config file
-d, --domain <domain> append — Add a domain seed; can be specified multiple times
-u, --url <URL> append — Add a URL seed; can be specified multiple times
-o, --output <directory> string output Output directory; overrides config output.dir
-v, --verbose flag false Verbose output (log level DEBUG)
--init flag false Generate a default config file and exit
--version flag false Show version info and exit
--depth <N> int — Maximum scan depth; overrides config max_depth
--resume flag false Resume an interrupted scan from the checkpoint
--watch flag false Watch mode: periodically rescan and report changes
--list-plugins flag false List plugins in the plugin directory and exit
--plugin-info <name> string — Show details of a specific plugin and exit
--web flag false Start the Web console (long-running service)
--port <N> int 8050 Web console port

Plugin extension arguments

A loaded plugin that implements register_cli(parser) merges its own command-line arguments into the main parser; they appear in --help. On conflicting argument names, the first registered one wins.

Seed Arguments

-d and -u can be mixed and repeated:

python main.py -d example.com -d example.org -u https://blog.example.com
  • At least one seed is required; otherwise it errors with No seed assets provided... and exits with code 1
  • Exception: when using --resume and the checkpoint already contains nodes, seeds may be omitted

Run Modes

Z-Sans has several run modes, which are approximately mutually exclusive:

1. Single Scan (default)

python main.py -d example.com --depth 3 -o reports

When the scan finishes, the checkpoint is saved automatically and a report is generated.

2. Resume from Breakpoint

python main.py -d example.com            # first scan (interrupted)
python main.py --resume                   # resume
python main.py -d example.com --resume    # resume while adding new seeds

See Resume from Breakpoint.

3. Watch Mode

python main.py -d example.com --watch

Periodically rescans, compares the delta, and outputs a change file (default every 3600 seconds). See Watch Mode.

4. Web Console

python main.py --web
python main.py --web --port 9000   # default 0.0.0.0:8050
ZSANS_WEB_PASSWORD='secret' python main.py --web   # require authentication

Once started, the console stays resident; press Ctrl+C to exit. Setting ZSANS_WEB_PASSWORD requires a password for all console endpoints (third-party clients can authenticate via the Authorization: Bearer or X-API-Key header). See Web Console.

5. Plugin Management

python main.py --list-plugins        # list all loaded plugins
python main.py --plugin-info myplug  # show details of a single plugin

Exit Codes

Exit Code Meaning
0 Success (including command modes such as --version, --init, --web)
1 Failure: no seed assets, plugin not found, scan did not complete successfully, etc.

Execution Order Notes

  1. Parse -c/--config first and initialize internationalization accordingly
  2. Append plugin CLI arguments
  3. Process in order: --version → --init → config load → --web → engine build → --list-plugins / --plugin-info → --resume → seeds → --watch / normal scan
Core Concepts Configuration Reference