# 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 dashboard's API keys page; paste a key to save it
```

`login` does not sign you in through the browser: it opens
[API keys](/dashboard/api-keys) so you can make one, asks you to paste it, and
saves it to `~/.config/openintents/config.json` (readable by you only). In CI
or headless agents, set a key instead, which takes precedence over the saved
one:

```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 input <id> --input <input id> (--value <answer> \| --decline \| --done)` | Answer what an intent in `requires_input` asked. `<input id>` is `input_request.id`. |
| `openintents pay <id>` | Open the payment link of an intent in `requires_payment`, where the payer takes the step their wallet needs. |
| `openintents cancel <id>` | Cancel an intent that hasn't paid. |
| `openintents login` | Save an API key for later commands. |

`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). `--payment-link` always
waits for the payer to approve the purchase at a payment link before it is
paid from their [wallet](/docs/wallets). `--wait` blocks
until the intent is final, or needs somebody: payment, a sign-in, or an answer
(see the exit codes below).

The CLI also has `customers`, `profiles`, `sessions`, `sign-ins` and
`secrets` commands (`openintents --help` lists every flag). The same
[customers](/docs/api#customers), [profiles](/docs/profiles),
[sessions](/docs/sessions) and [secrets](/docs/vault) are in the
[REST API](/docs/api) and the SDKs.

## Scripting

Every command takes `--json` and prints one JSON object per line, so agents
can parse it without scraping text. Exit codes: `0` completed (or still
queued or running), `1` failed or error, `2` needs payment, `3` cancelled, `4`
needs the payer to sign in (`requires_login`), `5` needs an answer from the
payer (`requires_input`).

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