# Run a tool

Submit a saved request with a fixed price revision, spending cap and idempotency key.

## Create request.json

Fill the template using the inspected contract. input must match inputSchema; maxChargeMicros must be a non-negative integer string derived from the inspected pricing unit and bounded volume. The CLI accepts balance funding only.

```
{
  "toolId": "<toolId from inspect>",
  "toolRevision": "<toolRevision from inspect>",
  "priceRevision": "<priceRevision from inspect>",
  "input": {
    "<required field>": "<value matching inputSchema>"
  },
  "idempotencyKey": "<unique key saved for this task>",
  "maxChargeMicros": "<integer spending cap in USD micro-units>",
  "funding": {
    "mode": "balance"
  }
}
```

## purrkey run

```
purrkey run --request request.json --wait 30s --output result.json
```

| Flag | Meaning |
| --- | --- |
| --request | Required request-file path. Use - to read JSON from stdin. The raw file and the normalized request must each fit in 1 MiB. |
| --wait | Maximum polling time, from 0 to 10m. Default 0 returns without additional polling. |
| --output | Save the complete JSON response to a local file. |
| --api-url | Optional API-origin override for an explicitly chosen deployment. |

## Reuse the file after interruption

The CLI writes a recovery journal before submission. Repeating the identical request file with the same API origin and API key recovers the operation; once a Run ID has been saved, the CLI retrieves that Run directly.

A changed request under the same idempotency key is a conflict. A new idempotency key means a new task and can create another charge. Rotating the API key does not change the server-side request identity within the same account. Preserve the original file when the submission result is uncertain.

- [Retrieve and cancel](/docs/cli/results): Poll an existing Run or request cancellation.