CLI Messages
See Errors & Warnings Catalog for the full index, and Errors & Warnings Guide for a narrative explanation of message categories, exit codes, and common fixes.
Messages from command-line argument parsing and subcommand dispatch.
| Message | Exit Code | Hint |
|---|---|---|
| CLI flag [option] requires a value but none was provided: [error message] | ||
| ❌ '--[option]' is specific to the '[command]' command | 2 | 💡 Place it after the subcommand: ssi [command] --[option] ... |
| ❌ Cannot use --[name] and --[option] together | 2 | 💡 Provide at most one of these flags |
| ❌ Cannot use --verbose and --quiet together | 2 | 💡 Use --verbose for more output, or --quiet for less |
| ❌ `auto` is no longer a valid copy method | 2 | 💡 Use `copy` instead — it uses reflink with automatic byte-copy fallback, which was what `auto` selected |
| ❌ Deployment symlink already exists: [path] | 1 | 💡 Remove the existing symlink first or use a different link path |
| ❌ Directory already exists: [path] | 2 | 💡 Choose a different directory name, or remove the existing directory first |
| ❌ Directory already exists and is not empty: [path] | 1 | 💡 Use a different directory or remove existing contents |
| 🧪 Dry run completed for [command] - no files modified | ||
| 🧪 Dry run for [operation]: completed successfully | ||
| A FatalError was constructed with a MessageId that has no exit_code configured — every fatal message must declare an exit_code in messages.toml (programming error) | ||
| Help display failed for no-args case: [error message] | ||
| ❌ Invalid value for [option] `[name]`: [error message] | 2 | 💡 Enter a value that matches the flag's documented type — run `ssi --help` or `ssi |
| ❌ unrecognized variant | 2 | |
| ❌ Missing required argument: [name] | 2 | 💡 Run `ssi [command] --help` to see usage |
| ❌ Cannot create site — path exists but is not a directory: [path] | 2 | 💡 Remove or rename the file or other entry blocking that path, or choose a different directory |
| ❌ No command specified | 2 | 💡 Run `ssi help` to see available commands |
| ❌ Symlink name must be a single filename component, not a path: [path] | 2 | 💡 Specify just the filename (e.g., 'prod'), not a path with separators (e.g., 'subdir/prod') |
| ❌ Destination '-' (stdout) requires --single-file | 2 | 💡 Use: ssi deploy --single-file <file> <source> - |
| Stdout flush failed: [I/O error message] | ||
| ❌ File not found in any page step: [path] | 2 | 💡 The path must be relative to the source directory and belong to a page step |
| ❌ Failed to write output to stdout | 1 | 💡 If piping output, check the receiving command completed successfully |
| Stdout write_all failed: [I/O error message] | ||
| ❌ SOURCE must be a directory, not a file | 2 | 💡 Use the directory containing ssi-config.toml 💡 Or use --config for custom config files |
| ❌ --suffix-length=[length] ignored when using --suffix=timestamp | 2 | 💡 --suffix-length only applies to random suffixes — remove it or use a different --suffix mode |
| ❌ Suffix length [current] is above the maximum ([max]) | 2 | |
| ❌ Not a valid number for --suffix-length: [error message] | 2 | |
| ❌ Suffix length cannot be 0; use 1 through [max] | 2 | |
| ❌ Too many arguments for '[command]' command | 2 | 💡 Run `ssi [command] --help` to see usage |
| ❌ --trace-tokens requires --single-file | 2 | 💡 Use: ssi deploy --single-file <file> <source> <dest> --trace-tokens |
| ❌ Unknown flag: [name] | 2 | 💡 Run `ssi --help` to see available options |
| ❌ Unknown command: [name] | 2 | 💡 Run `ssi --help` to see available commands |
| ❌ | 1 | 💡 Review the errors above and fix them in your source files or ssi-config.toml |