# CLI for agents

The `bird` CLI is a single binary built to be driven by an agent. Output is JSON by default, errors go to stderr, and exit codes carry the failure category.

## Get set up

The fastest path is to [set up your coding agent](/docs/ai/set-up-your-agent): paste one prompt and your agent installs the CLI and Bird's skills for you. To install it by hand:

```bash
curl -fsSL https://cli.bird.com/install.sh | sh
bird auth login
```

`bird auth login` runs a browser OAuth flow and stores a grant bound to one workspace and its region, so there is no API key and no host to configure. `bird auth status` always exits `0` and reports `valid: true` once the token works. `bird whoami` returns the signed-in user (id, email, name) — who the agent is acting as, and the same identity the MCP `whoami` tool returns.

## The contract

- JSON to stdout; errors and diagnostics to stderr; never mixed.
- Exit codes: `2` invalid input, `3` not found, `4` auth or permission, `1` anything else.
- Mutations take input from flags, a JSON body via `--body-file -` (stdin), or both, with the flag winning.
- `--example` prints a valid request body, `--dry-run` previews the request without sending, and `--idempotency-key` makes a retry safe.

## Next steps

- [Set up your coding agent](/docs/ai/set-up-your-agent): paste a prompt and your agent installs the CLI and skills.
- [Agent skills](/docs/ai/agent-skills): what each skill teaches your agent.
- [CLI reference](/docs/cli): every command, flag, and output shape.
- [MCP server](/docs/ai/mcp-server): the same Bird surface as MCP tools, for agents that call tools instead of running a shell.