# CLI

`openintents` is a thin command-line client for the [REST API](/docs/api),
built for shell-driven agents and for humans testing intents. It ships with
the TypeScript SDK and is open source:
[github.com/tinyhumansai/openintents](https://github.com/tinyhumansai/openintents).

## Install and sign in

```bash
npm install -g @tinyhumansai/openintents
openintents login          # opens the browser; stores a key in ~/.config/openintents
```

In CI or headless agents, set a key instead:

```bash
export OPENINTENTS_API_KEY=oi_live_...
```

## Commands

| Command | What it does |
| --- | --- |
| `openintents run "<intent>"` | Create an intent. Prints its ID. |
| `openintents status <id>` | Show an intent's status and result. |
| `openintents list [--status s]` | Recent intents. |
| `openintents pay <id>` | Open the payment link of an intent in `requires_payment`. |
| `openintents cancel <id>` | Cancel an intent that hasn't paid. |
| `openintents balance` | Show the agent balance and this month's spend. |

`run` accepts the same options as the API:

```bash
openintents run "UberX to SFO, leaving 7am" \
  --max 60 \
  --context pickup="500 Howard St" \
  --wait
```

`--max` is in dollars (sent as `max_amount` in cents). `--wait` blocks until
the intent is completed, failed or needs payment.

## Scripting

Every command takes `--json` and prints one JSON object per line, so agents
can parse it without scraping text. Exit codes: `0` completed, `1` failed or
error, `2` needs payment, `3` cancelled.

```bash
id=$(openintents run "large pepperoni pizza to the office" --max 40 --json | jq -r .id)
openintents status "$id" --wait --json | jq '.result.total'
```