CLI reference

The opentide command is a Typer application included in the core package:

pip install 'opentide==0.18.0'

Run opentide --help for the live command tree.

Command overview

Global options

All commands inherit global options:

Typical CI sequence

opentide generate
opentide --json validate --strict
opentide validate query --platform sentinel --live
opentide lint --strict
opentide deploy --platform sentinel --dry-run --strategy PREVIEW --all

Generated pipelines use opentide generate docs --output docs for documentation jobs. Status promotion runs inside opentide deploy — there is no separate mutate promote step.

JSON output

With --json, every command writes exactly one JSON document to stdout. Successes include "ok": true; failures include "ok": false, a status, message, and non-zero exit code. Diagnostics use stderr and never prefix the stdout document. (opentide info emits the info object through the same contract.)

Exit codes

Commands set a process exit code so CI can gate without parsing output: 0 success, 1 error, 2 usage error. Full reference: Exit codes.

Coding agents

An agent in a shell drives the same commands as a person. Four rules cover it, and opentide setup skills writes them into AGENTS.md, CLAUDE.md and .github/copilot-instructions.md:

1. Run opentide --json <command>. stdout is one JSON document and nothing else.
2. Branch on the exit code first, then read failure.code for the detail, for example issues_found, usage_invalid_choice or no_tenant_reached. A usage error carries the closest valid value in failure.suggestion.
3. Apply each finding's fix: every edit replaces the text from (line, column) up to (end_line, end_column), 1-based, with replacement. safe: true edits only respell the same word and can be applied as they are; check the others against help. For a finding with no fix, opentide explain <code> says what it means and how to fix it.
4. Follow next_actions, each a {command, reason}.

The loop: search what exists (opentide --json info coverage --technique T1059), draft from .opentide/templates/, run opentide --json validate --file <file> until ok is true, then preview with opentide --json deploy --dry-run --strategy PREVIEW --all. People review and merge the change and run real deployments. An agent never gets a prompt: a command that needs input exits 2 with usage_needs_input and names the flags to pass.

Command tree for agents

opentide --json commands prints every visible command, read from the CLI itself, so it never drifts from what the CLI accepts:

opentide --json commands

{
  "program": "opentide",
  "version": "0.18.0",
  "global_options": [
    {
      "name": "repo",
      "flags": ["--repo"],
      "secondary_flags": [],
      "type": "string",
      "choices": null,
      "default": null,
      "required": false,
      "multiple": false,
      "is_flag": false,
      "envvars": ["OPENTIDE_REPO_ROOT"],
      "help": "Repository root"
    }
  ],
  "commands": [
    {
      "path": "validate query",
      "name": "query",
      "summary": "Check rule queries on the platform's tenants (needs --live).",
      "help": "Check rule queries on the platform's tenants (needs --live). …",
      "group": false,
      "runs_alone": true,
      "subcommands": [],
      "deprecated": false,
      "arguments": [],
      "options": [
        {
          "name": "platform",
          "flags": ["--platform"],
          "type": "choice",
          "choices": ["sentinel", "splunk", "crowdstrike", "…"],
          "required": true,
          "…": "…"
        }
      ],
      "example": "opentide validate query --platform sentinel --live",
      "output_schema": {
        "anyOf": [
          { "$ref": "#/$defs/QueryValidationResult" },
          { "$ref": "#/$defs/CommandError" }
        ]
      }
    }
  ],
  "$defs": { "QueryValidationResult": { "…": "…" }, "CommandError": { "…": "…" } },
  "ok": true,
  "status": "completed",
  "message": "55 commands",
  "summary": { "commands": 55, "groups": 14 },
  "…": "envelope keys"
}

Without --json, opentide commands prints the tree, one command per line with its summary, and ends with ✓ 55 commands. Listing the tree imports every command's module once; it never loads the detection registry.

Choosing between CLI, SDK, and MCP

The CLI is one of three interfaces to the same engine. For humans and pipelines, use the CLI; to embed in Python, use the SDK; for AI agents, use MCP. See Choosing an interface.

Shell completion

opentide --install-completion        # the current shell
opentide --show-completion zsh       # print the script for zsh

Completion also fills in object UUIDs, object files, ATT&CK techniques, platforms and strategies from the workspace; see Global options → Shell completion.

Source

Command definitions: src/opentide/cli/commands/ (the root list is src/opentide/cli/commands/__init__.py; global options are in src/opentide/cli/root.py), src/opentide/cli/setup_app.py, src/opentide/cli/share_app.py.