Store commands
The poltura store commands read records and run actions in a store from a terminal, and poltura mcp connect sets up AI tools.
On this page
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. Not on npm yet
Connect
poltura store uses, in this order, --token, POLTURA_TOKEN (an API token), and then your
poltura login sign-in, which is renewed before it expires. For a person at a terminal, sign in:
poltura login
poltura store infoFor a script, create a token with the permissions the commands need and set it in the environment:
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.)
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
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.
poltura store product list --limit 5
poltura store order get 019bb3ef-6501-7dc3-a2e7-726e91520b7a --include paymentspoltura store <record_type> listtakes the record type's filters as flags, or--filter '{"status":"pending"}'as JSON, plus--sort,--fields,--limit(1 to 100, default 20),--cursorand--detailed.poltura store <record_type> get <id>takes--include,--fieldsand--detailed.
Run poltura store <record_type> list --help to see the filters and sorts of one type.
Run actions
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 --waitThe action takes the key shown in the tool 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.
| 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
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.
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. |
--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.