# Connect Your Agent

One paste and the agent can drive every platform in the definition. Drop the snippet below into the agent's instructions — a system prompt, a `CLAUDE.md`, an `AGENTS.md`, wherever the agent reads its rules. It bootstraps the first `discovery` call; the CLI teaches the agent everything else at runtime.

## The drop-in snippet

```
## OmniCLI platform actions

You have `omni-cli`: one CLI for the external platforms in this project's definition.

- Discover before you invoke. `omni-cli discovery` lists platforms; `omni-cli discovery
  <platform>` lists that platform's actions; `omni-cli discovery <platform> <action-id>`
  returns one action's params and output schema. Never guess a flag — read the action first.
- Invoke as `omni-cli <platform> <resource> <verb> --flag value --json`. Every param is a
  long flag `--<name>` with a string value; there are no positional arguments.
- Always pass `--context work` or `--context personal` explicitly.
- Branch on the exit code: 0 = payload on stdout; non-zero = structured JSON error on
  stderr. Never parse stdout to detect failure.
- The CLI never retries anything. Re-issue a failed call only if the error's
  `upstream.idempotent` is true; on exit 12 (rate_limited) wait
  `upstream.retry_after_seconds` first.
- You may run only these operational commands: `context`, `definitions`, `version`,
  `errors`, `discovery` — plus the platform actions discovery lists.
- NEVER run `login`, `logout`, `account`, or `self-update` — those are human-only. On
  exit 4, 5, or 6 (auth is missing or interactive), stop and ask the human to run the
  remedy command from the error.
```

## Why this is enough

The snippet doesn't have to carry the full contract because every `discovery` response does. All discovery output — any tier, even logged out — rides with the same scaffolding blocks: `invocation` (the grammar and flag binding), `global_flags`, `envelope` (the output contract), `pagination`, `auth`, `operational_commands`, `human_only`, and `errors` (the full exit-code catalog). Any single call is self-sufficient, so an agent that forgets everything but "run `omni-cli discovery`" can recover the rest. Details in [Discovery Contract](https://omnicli.io/docs/discovery-contract.md) and [Invocation & Envelope](https://omnicli.io/docs/invocation-and-envelope.md).

## Machine-readable docs

Agents that want the prose too can fetch it directly: https://omnicli.io/llms.txt indexes this documentation, and every page is served as plain markdown at `https://omnicli.io/docs/<slug>.md`.

## What your agent can and can't do

| Task | Command | Who runs it |
| --- | --- | --- |
| Discover platforms and actions | `omni-cli discovery [<platform>] [<action-id>]` | Agent |
| Run platform actions | `omni-cli <platform> <resource> <verb> ...` | Agent |
| Manage context | `omni-cli context ...` | Agent |
| Refresh the definition | `omni-cli definitions ...` | Agent |
| Read build info and the error catalog | `omni-cli version`, `omni-cli errors` | Agent |
| Platform sign-in / sign-out | `omni-cli <platform> login \| logout` | Human |
| Account sign-in (device flow) | `omni-cli account login` | Human |
| Update the binary | `omni-cli self-update` | Human |

The human-only split is enforced, not just advised: authentication is interactive by design (no token env var, no piped stdin), and a non-interactive attempt exits 6 (`interactive_required`). When the agent hits exit 4, 5, or 6, the structured error's `remedy` field carries the exact command to hand to a human — see [Exit Codes](https://omnicli.io/docs/exit-codes.md).