Discovery Contract

omni-cli discovery is the machine-readable contract between the CLI and the agent: what platforms exist, what actions they carry, and exactly how to call each one. It always emits JSON — no --json flag needed — and it is tiered so an agent loads only what it needs.

Three tiers

Per-action schemas are heavy; an agent rarely needs more than one at a time. Discovery splits the surface so the always-loaded top level stays small and the full schema arrives only when the agent drills into the action it intends to run.

omni-cli discovery                        # tier 1: platform index
omni-cli discovery <platform>             # tier 2: that platform's actions
omni-cli discovery <platform> <action-id> # tier 3: one action in full

Tier 1 — platform index

Platform headers only, no actions. Each entry carries pre-computed action_count and mutating_count so the agent reads totals instead of aggregating tier-2 responses itself.

{
  "discovery_schema_version": "2.2.0",
  "authenticated": true,
  "definition_id": "def_8f3a…",
  "platforms": [
    { "key": "github", "display_name": "GitHub", "host_required": false,
      "action_count": 21, "mutating_count": 8 },
    { "key": "jira", "display_name": "Jira", "host_required": true,
      "action_count": 14, "mutating_count": 6 }
  ],
  "invocation": { "…": "…" }, "global_flags": [ "…" ], "envelope": { "…": "…" },
  "pagination": { "…": "…" }, "auth": { "…": "…" },
  "context": { "contexts": ["work", "personal"], "current": "work", "source": "default",
    "status_command": "omni-cli context status --json", "note": "…" },
  "operational_commands": ["context", "definitions", "version", "errors", "discovery"],
  "human_only": { "…": "…" }, "errors": [ "…" ]
}

Tier 2 — one platform's action list

Just enough to pick an action: id, argv, summary, mutating, tier_min. No params, no output schemas.

{
  "platform": { "key": "github", "display_name": "GitHub", "host_required": false },
  "actions": [
    { "id": "issue.list", "argv": ["github", "issue", "list"],
      "summary": "List or filter issues.", "mutating": false, "tier_min": "free" },
    { "id": "issue.create", "argv": ["github", "issue", "create"],
      "summary": "Open a new issue.", "mutating": true, "tier_min": "free" }
  ],
  "…scaffolding blocks as in tier 1…": {}
}

Tier 3 — one action in full

Everything needed to invoke and parse: params (the input), output_schema (the output), mutating/idempotent/tier_min/interactive, plus pagination and order when the action pages or sorts, a host block on host-required platforms, and a ready-to-run example_invocation.

{
  "platform": { "key": "github", "display_name": "GitHub", "host_required": false },
  "action": {
    "id": "issue.list", "resource": "issue", "verb": "list",
    "summary": "List or filter issues.",
    "argv": ["github", "issue", "list"],
    "params": [
      { "name": "repo", "type": "string", "required": true,
        "description": "owner/name repository slug.", "example": "octo/hello" },
      { "name": "state", "type": "enum", "required": false,
        "values": ["open", "closed", "all"], "description": "Filter by state." }
    ],
    "output_schema": { "type": "array", "items": { "…": "…" } },
    "mutating": false, "idempotent": true, "tier_min": "free", "interactive": false,
    "pagination": { "cursor_param": "page",
                    "next": { "from": "header", "header": "Link", "rel": "next" } },
    "example_invocation": "omni-cli github issue list --repo octo/hello --json"
  },
  "…scaffolding blocks as in tier 1…": {}
}

example_invocation is assembled only from the declared examples of the action's required params — if any required param lacks one, the field is omitted rather than invented. An example that lies is worse than none.

Scaffolding on every response

Every tier — and every gated response below — carries the same scaffolding blocks, so any single discovery call is self-sufficient:

invocation — the command grammar, flag binding, and host rules (see Invocation & Envelope)
global_flags — --context, --json, --verbose
envelope — the output contract and retry rule
pagination — the single-page rule and how to advance
auth — authentication is human-only, and (when signed in) which contexts already hold a credential per platform
context — which contexts exist (work, personal), the one that resolves for the current invocation (current, null when none does, with source naming the step of the resolution chain that won), and the command to re-check (omni-cli context status --json); per-context login state stays in auth
operational_commands — the agent-runnable commands: context, definitions, version, errors, discovery
human_only — login, logout, account, self-update, each with the remedy a human follows
errors — the full exit-code catalog

Schema versioning

discovery_schema_version (currently 2.2.0) versions the JSON shape itself, independently of the binary version. It bumps on any breaking change to the discovery format, so a consumer detects contract changes without diffing binaries. The binary's own version lives under omni-cli version.

Logged out or expired

Discovery never goes dark. When there is no account session — or the definition's entitlement has expired — the platform surface and definition_id are omitted, but all scaffolding still ships, so an agent can learn how to direct a human to sign in. A top-level message and remedy distinguish the two states: not signed in (omni-cli account login) vs. expired (omni-cli account status).

A gated drill-down is acknowledged, not answered: the response echoes what was asked via requested and unavailable (exit 0), without validating the names against the hidden catalog.

{
  "discovery_schema_version": "2.2.0",
  "authenticated": false,
  "message": "not authenticated — log in to list your definition's platforms and actions",
  "remedy": "omni-cli account login",
  "requested": { "platform": "github", "action": "issue.list" },
  "unavailable": "platform detail requires login",
  "…scaffolding blocks as in tier 1…": {}
}

Unknown platform or action

When signed in, a drill-down into a platform or action that doesn't exist fails with exit 2 (usage_error) and a remedy listing the valid options — an unknown platform lists the available platform keys; an unknown action points at omni-cli discovery <platform> to recover the valid ids. The agent self-corrects without a second guess.

Read this page as markdown — the copy your coding agent fetches.