# Store commands (/ai/store-cli)

`poltura store` gives a terminal and a script the same records and actions an AI client has, with the same
permission checks, approvals and limits. `poltura mcp connect` writes the MCP configuration for an AI tool. Both
come with `@poltura/cli`; the install, `poltura login` and the shared flags are on the [CLI page](/apps/cli). (Not published to npm yet.)

## Connect [#connect]

`poltura store` uses, in this order, `--token`, `POLTURA_TOKEN` (an [API token](/api/tokens)), and then your
`poltura login` sign-in, which is renewed before it expires. For a person at a terminal, sign in:

```bash
poltura login
poltura store info
```

For a script, create a token with the permissions the commands need and set it in the environment:

```bash
export POLTURA_TOKEN=pltu_...
poltura store info
```

| Flag | Environment variable | Meaning |
| --- | --- | --- |
| `--token <token>` | `POLTURA_TOKEN` | The API token. Without one the command uses the stored sign-in. |
| `--store <id>` | `POLTURA_STORE` | The store, when the credential reaches more than one. A credential for one store needs no flag. |
| `--api <url>` | `POLTURA_API` | The API address. The default is `https://api.poltura.com`, or the address of your last sign-in. |

Every `poltura store` command accepts `--json` to print machine-readable output. A call that the points budget
refused is not retried for you here; wait the time the message gives and run it again with the same
`--idempotency-key`. (`poltura theme` commands do wait and retry; see [Exit codes and retries](/apps/cli#exit-codes-and-retries).)

## Look around [#look-around]

| Command | Does |
| --- | --- |
| `poltura store info` | The store, what the token may do in it, and what is available. |
| `poltura store search <query>` | Searches records across types by name. `--type` narrows it, `--limit` sets how many hits (1 to 50). |
| `poltura store actions [query]` | Lists the actions the token can run, filtered by words. |
| `poltura store describe <action>` | One action: what it does, its input, its flags and its approval rule. |
| `poltura store analytics <pql>` | Runs an analytics query. |

## Read records [#read-records]

Every record type the token can read becomes a command, taken from the store's own schema, so a new record type
needs no new CLI release.

```bash
poltura store product list --limit 5
poltura store order get 019bb3ef-6501-7dc3-a2e7-726e91520b7a --include payments
```

- `poltura store <record_type> list` takes the record type's filters as flags, or `--filter '{"status":"pending"}'`
  as JSON, plus `--sort`, `--fields`, `--limit` (1 to 100, default 20), `--cursor` and `--detailed`.
- `poltura store <record_type> get <id>` takes `--include`, `--fields` and `--detailed`.

Run `poltura store <record_type> list --help` to see the filters and sorts of one type.

## Run actions [#run-actions]

```bash
poltura store run product.update --product-id 019bb58e-0ec1-79c1-9f40-d39d8d07674b --title "Linen apron"
poltura store run payment.refund --payment-id 019bb4b5-6430-7a01-8e17-6df1bfccb8e5 --amount 1200 --dry-run
poltura store run payment.refund --payment-id 019bb4b5-6430-7a01-8e17-6df1bfccb8e5 --amount 1200 --destructive --wait
```

The action takes the key shown in the [tool reference](/ai/reference), such as `product.update`, or its tool name.
The action's input fields become flags, or come from a JSON file with `--input <file>` (`-` reads standard input).
`poltura store describe <action>` lists them.

| Flag | Meaning |
| --- | --- |
| `--dry-run` | Validates and previews without changing anything. Only for actions marked "Dry run". |
| `--idempotency-key <key>` | A key of 8 to 200 characters. Repeating the command with the same key returns the first result. |
| `--destructive` | Required for an action that cannot be undone. Without it the command stops and tells you to check with `--dry-run` first. |
| `--wait` | When the action needs approval, wait for the decision instead of returning. |
| `--input <file>` | The action input as a JSON object. Flags override it. |

When an action needs approval, the command prints the approval link, the expiry and the run id. Without
`--wait` it then exits with code 3. A person approves it in the store admin under **Agent requests**, as described
in [How agents act on your store](/ai/agents#approval).

| Exit code | Meaning |
| --- | --- |
| 0 | Done. |
| 1 | The action failed, was rejected or expired. |
| 2 | Wrong usage, such as a missing flag. |
| 3 | Waiting for approval. |

## Connect an AI tool [#connect-an-ai-tool]

`poltura mcp connect [tool]` adds the Poltura MCP server to the tool's configuration file. The tool is `claude`,
`cursor`, `vscode` or `codex`; without a name it configures every one it finds on this machine.

```bash
poltura mcp connect claude
poltura mcp connect cursor --mode typed
poltura mcp connect codex --token-env
```

| Option | Meaning |
| --- | --- |
| `--mode <mode>` | `compact` (default) or `typed`. See [MCP server](/ai/mcp#two-modes). |
| `--store <id>` | Pins the connection to one store. |
| `--token-env [name]` | Authenticates with an API token read from an environment variable (default `POLTURA_TOKEN`) instead of signing in. The token itself is never written to a file. |
| `--global` | Writes the tool's user-level file instead of the project's. |
| `--name <name>` | The server name in the file. The default is `poltura`. |
| `--url <url>` | A different server address. |
| `--dry-run` | Prints what would be written and changes nothing. |

The files it writes:

| Tool | File |
| --- | --- |
| Claude Code | `.mcp.json` in the project, or `~/.claude.json` with `--global` |
| Cursor | `.cursor/mcp.json`, or `~/.cursor/mcp.json` with `--global` |
| VS Code | `.vscode/mcp.json` |
| Codex | `~/.codex/config.toml` |

The command keeps everything else in the file, only adds or updates the `poltura` entry, and refuses to touch a
file that is not valid. It ends by saying what to do next: usually to open the tool and sign in to Poltura, or for
Codex to run `codex mcp login poltura`.