Setup Assistant CLI

Rules

1. Invoke the packaged executable as event-setup; command families are bare first arguments. Never prefix them with setup.
2. Use --machine for automation. Read the single event-setup-command/v1 JSON object and branch on exitCode, diagnostics, coverage, and readiness; do not scrape Spectre-rendered text output.
3. Pass artifacts through --input and --output. Use - only where the command accepts standard input or text-mode standard output.
4. Never place passwords, tokens, credentials, private keys, API keys, or connection strings in arguments, input paths, environment names, logs, or retained command output. The CLI rejects secret-bearing surfaces.
5. Treat --dry-run as planning only. An artifact reports writeStatus as planned until a non-dry-run command writes it.
6. Do not invent command aliases. The checked machine schema at schemas/event-setup-command-v1.schema.json is generated from the same Spectre.Console.Cli registry that owns executable grammar and settings.
7. Operator-identity export and import are offline integrity operations. Their output is sensitive, and successful CLI validation is not target readiness or permission to mutate a server.
8. Human help and results are non-interactive Spectre.Console output. Machine mode bypasses rich rendering and remains ANSI-free; never redirect or parse the human surface for automation.
9. Hostile arguments are rejected before Spectre parsing so parser diagnostics cannot echo secret-looking names, paths, identity values, or control text. Treat a bounded diagnostic code as the complete failure detail.

Workflow

1. Confirm the binary and machine contract:

   event-setup doctor --machine
   

2. Inspect the public configuration catalogue without writing an artifact:

   event-setup catalogue list --machine --dry-run
   

3. Validate an existing dotenv file:

   event-setup env validate --input deployment.env --machine
   

4. Render a topology-specific dotenv artifact only after selecting explicit non-secret capabilities and providers:

   event-setup env render --topology standalone --provider sqlite --output deployment.env --machine
   

5. Validate configuration portability artifacts before promotion:

   event-setup manifest validate --input instance-manifest.json --machine
   event-setup tenant-package validate --input tenant-package.json --machine
   

6. Export an operator-identity portability artifact, then prepare a server import request against the exact current revision:

   event-setup portability export-operator-identity --input operator-identity.json --output operator-identity.yaml --format yaml --machine
   event-setup portability import-operator-identity --input operator-identity.yaml --output operator-identity-import.json --expected-revision "$EXPECTED_REVISION_SHA256" --machine
   

   Use --expected-revision absent only when the target has no current operator-identity document. The import result remains incomplete until server validation and authorization succeed.

7. Validate a legal draft before it enters an operator review:

   event-setup legal validate --input legal-draft.json --machine
   

Verification

• event-setup doctor --machine exits 0 and emits one newline-terminated JSON object with schemaVersion equal to event-setup-command/v1.
• event-setup --help and family help are generated by the registered Spectre grammar; no legacy command aliases or fallback parser exist.
• Reject any instruction using a setup prefix or a command family absent from the checked schema.
• Treat exit codes 2, 3, 4, 64, 65, 70, and 74 as failure states; do not infer success from an empty diagnostic list alone.