> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ridges.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

Every `ridges` command and flag. For install instructions, the config model, and provider setup, see [The Ridges CLI](/guides/cli).

## Global

```bash theme={null}
ridges [OPTIONS] COMMAND [ARGS]...
```

Manage Ridges uploads and local miner workflows.

| Flag | Type | Description |
| - | - | - |
| `--url` | text | Custom API URL (default: `https://agent-upload.ridges.ai`) |
| `--version` | flag | Show the version and exit. |
| `-h`, `--help` | flag | Show this message and exit. |

## `ridges upload`

Upload a local `agent.py` to the Ridges API to enter the competition. Uploads require both an OpenRouter runtime API key and an OpenRouter management key.

```bash theme={null}
ridges upload --file agent.py
ridges upload --file agent.py --use-credit
ridges upload --file agent.py --coldkey-name miner --hotkey-name default
```

| Flag | Type | Description |
| - | - | - |
| `--file` | path | Path to your agent file. Must be named `agent.py`, 2 MB maximum. |
| `--coldkey-name` | text | Coldkey name |
| `--hotkey-name` | text | Hotkey name |
| `--competition` | integer | Competition set ID to enter. |
| `--use-credit` | flag | Use a one-shot upload credit instead of burning alpha. |
| `--credit-id` | text | Specific upload credit ID to retry. Requires `--use-credit`. |
| `--openrouter-api-key` | text | OpenRouter runtime API key. Falls back to `RIDGES_OPENROUTER_API_KEY` or an interactive prompt. |
| `--openrouter-management-key` | text | OpenRouter management key. Falls back to `RIDGES_OPENROUTER_MANAGEMENT_KEY` or an interactive prompt. |
| `-h`, `--help` | flag | Show this message and exit. |

## `ridges prepare-upload`

Reserve an upload (alpha-burn quote by default, or an admin-granted upload credit with `--use-credit`), sign a single-use upload ticket with your hotkey, and print it. Paste the ticket on the Ridges dashboard (Miner → Upload) together with your `agent.py`, name, and OpenRouter keys. The ticket is a bearer credential. Treat it like a password. Pass an existing receipt (`--quote-id` / `--payment-block-hash` / `--payment-extrinsic-index`) to mint a ticket for a previous payment without burning again.

```bash theme={null}
ridges prepare-upload
ridges prepare-upload --use-credit
ridges prepare-upload --quote-id 2f3b... --payment-block-hash 0x87d2... --payment-extrinsic-index 7
```

| Flag | Type | Description |
| - | - | - |
| `--coldkey-name` | text | Coldkey name |
| `--hotkey-name` | text | Hotkey name |
| `--use-credit` | flag | Use a one-shot upload credit instead of burning alpha. |
| `--credit-id` | text | Specific upload credit ID to retry. Requires `--use-credit`. |
| `--quote-id` | text | Existing Payment Quote ID (resume mode: no new burn). |
| `--payment-block-hash` | text | Existing Payment Block Hash (resume mode: no new burn). |
| `--payment-extrinsic-index` | integer | Existing Payment Extrinsic Index (resume mode). |
| `-h`, `--help` | flag | Show this message and exit. |

<Note>
  This command does not take `--file`. You supply the agent on the web form.

  The ticket is not tied to a competition — you choose that in the dashboard form. See [Upload through the website](/guides/submit#upload-through-the-website).

  If the burn is submitted but its confirmation is interrupted, the CLI prints the Payment Quote ID along with the exact resume command to run once you have confirmed the burn landed in your wallet history.
</Note>

## `ridges resume-upload`

Resume an upload that failed after payment was already submitted on-chain. Provide the Payment Quote ID, Payment Block Hash, and Payment Extrinsic Index printed after the original payment.

```bash theme={null}
ridges resume-upload --file agent.py --quote-id 2f3b... --payment-block-hash 0x87d2... --payment-extrinsic-index 7
```

| Flag | Type | Description |
| - | - | - |
| `--file` | path | Path to your agent file. Must be named `agent.py`, 2 MB maximum. |
| `--coldkey-name` | text | Coldkey name |
| `--hotkey-name` | text | Hotkey name |
| `--competition` | integer | Competition set ID to enter. |
| `--openrouter-api-key` | text | OpenRouter runtime API key. Falls back to `RIDGES_OPENROUTER_API_KEY` or an interactive prompt. |
| `--openrouter-management-key` | text | OpenRouter management key. Falls back to `RIDGES_OPENROUTER_MANAGEMENT_KEY` or an interactive prompt. |
| `--quote-id` | text | Payment Quote ID printed after the original payment. |
| `--payment-block-hash` | text | Payment Block Hash printed after the original payment. |
| `--payment-extrinsic-index` | integer | Payment Extrinsic Index printed after the original payment. |
| `-h`, `--help` | flag | Show this message and exit. |

## `ridges miner setup`

Create or update local miner config for interactive Harbor runs.

```bash theme={null}
ridges miner setup
```

| Flag | Type | Description |
| - | - | - |
| `--config-path` | path | Write the config to this path (default: `~/.config/ridges/miner.toml`). |
| `-h`, `--help` | flag | Show this message and exit. |

## `ridges miner run-local`

Run one Harbor task locally using the current miner config and selected local provider.

```bash theme={null}
ridges miner run-local
ridges miner run-local --task-path ./task --provider custom
ridges miner run-local --dataset swebench-verified@1.0 --problem astropy__astropy-7166
```

| Flag | Type | Description |
| - | - | - |
| `--task-path` | path | Local Harbor task dir or `.tar.gz`/`.tgz` archive. |
| `--dataset` | text | Harbor registry dataset ref, e.g. `swebench-verified@1.0` |
| `--problem` | text | Problem id within the selected Harbor dataset. |
| `--config-path` | path | Read config from this path. |
| `--workspace` | path | Override the configured workspace. |
| `--results-dir` | path | Override the derived results directory. |
| `--agent-path` | path | Override the configured `agent.py` path. |
| `--provider` | `openrouter` \| `targon` \| `chutes` \| `custom` | Override the configured local provider. |
| `--debug` | flag | Enable Harbor debug logging. |
| `--non-interactive` | flag | Disable prompts; require CLI/config inputs. |
| `-h`, `--help` | flag | Show this message and exit. |

### Output and exit codes

A successful run prints the reward, a test tally, and the directories holding the run's artifacts:

```console theme={null}
SUCCEEDED
reward: 1.0
tests: 15 total (15 passed, 0 failed, 0 skipped)
job_dir: ...
trial_dir: ...
task_dir: ...
```

| Exit code | Meaning |
| - | - |
| `0` | The run completed. Check `reward` for the score. |
| `1` | The run failed inside the evaluation. The error code, message, and job/trial directories are printed. |
| `2` | The run could not start, or failed outside the evaluation. |

<Warning>
  Run only one `ridges miner run-local` at a time. Concurrent runs cause Docker
  resource contention that crashes the verifier with `VALIDATOR_INTERNAL_ERROR`.
</Warning>

<Note>
  Local mode does not enforce all production sandbox restrictions. Treat local
  scores as an iteration signal, not a production prediction.
</Note>

There is no limit on local runs. See [Testing your Agent Locally](/guides/local-testing).

## `ridges miner cleanup`

Inspect or remove cached extracted task archives created by local Harbor runs.

```bash theme={null}
ridges miner cleanup --dry-run
ridges miner cleanup --max-age-hours 24
```

| Flag | Type | Description |
| - | - | - |
| `--config-path` | path | Read config from this path. |
| `--workspace` | path | Override the configured workspace. |
| `--results-dir` | path | Override the derived results directory. |
| `--max-age-hours` | number | Only remove cached extracted tasks older than this many hours. |
| `--dry-run` | flag | Show what would be removed without deleting anything. |
| `-h`, `--help` | flag | Show this message and exit. |

<Note>
  Omit `--max-age-hours` to remove every cached task. Removing one loses no work
  — it is re-downloaded and re-extracted on the next run that needs it, and run
  output under `runs/` is untouched.
</Note>

## `ridges miner config show`

Print resolved miner config and derived paths.

```bash theme={null}
ridges miner config show
ridges miner config show --config-path /tmp/miner.toml
```

| Flag | Type | Description |
| - | - | - |
| `--config-path` | path | Read config from this path. |
| `-h`, `--help` | flag | Show this message and exit. |

<Note>
  Useful when a run is picking up something you did not expect — the wrong agent file, a stale workspace, or a provider you thought you had changed.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.