---
title: "CLI Reference"
description: "Every command the ironclaw binary provides"
icon: terminal
---

IronClaw ships as a single binary named `ironclaw`. Every command is a subcommand — running
`ironclaw` on its own prints usage and exits without starting anything.

```bash
ironclaw --help
ironclaw --version
```

---

## Running the Agent

| Command | What it does |
| --- | --- |
| `ironclaw serve` | Start the [web interface](/using/webui) on `127.0.0.1:3000` |
| `ironclaw repl` | Start an interactive terminal session with the agent |
| `ironclaw run -m "<message>"` | Send a single message and exit |
| `ironclaw status` | Print a runtime status snapshot |
| `ironclaw doctor` | Check configuration and driver health without creating state |

```bash
ironclaw run -m "What changed in my repo today?"
```

`doctor` is the first thing to run when something isn't working. It reports your home
directory, active profile, whether configuration files were found, and whether each
driver initialized.

---

## Setup and Configuration

| Command | What it does |
| --- | --- |
| `ironclaw onboard` | One-time setup — see [Onboard](/onboard) |
| `ironclaw config path` | Show resolved configuration paths without creating state |
| `ironclaw config init` | Write a commented `config.toml` and `providers.json` stub |
| `ironclaw config list` | List every configuration key and its current value |
| `ironclaw config get <key>` | Read one value by dot-separated key |
| `ironclaw config set <key> [value]` | Write one value; secret keys omit it and prompt |
| `ironclaw profile list` | List the available boot profiles |

```bash
ironclaw config get llm.default.provider_id
ironclaw config set google.client_id <your-client-id>
```

`config init` refuses to overwrite existing files unless you pass `--force`.

`config list` and `config get` read every key. `config set` is narrower: it accepts only
`<provider>.api_key`, `google.client_id`, `google.client_secret`, `google.redirect_uri`,
and `webui.token --rotate`, routing each to the configuration file, the encrypted secret
store, or the web token file. Other supported settings are edited in `config.toml`
directly; retired keys such as `slack.enabled` are refused with migration guidance.

`config set` does not restart the running instance — it prints `to apply: ironclaw service
restart`. See [Configuration](/capabilities/configuration).

---

## Models and Providers

| Command | What it does |
| --- | --- |
| `ironclaw models list` | List available inference providers, or show one |
| `ironclaw models status` | Show which model route is active |
| `ironclaw models set <model>` | Set the default model for the active provider |
| `ironclaw models set-provider <provider>` | Set the default provider |

```bash
ironclaw models list
ironclaw models set-provider anthropic --model claude-sonnet-4-20250514
ironclaw models status
```

See [Inference Providers](/capabilities/llm-providers) for the full catalog.

---

## Extensions and Skills

| Command | What it does |
| --- | --- |
| `ironclaw extension search <query>` | Search available extension packages |
| `ironclaw extension install <name>` | Install an extension package |
| `ironclaw extension remove <name>` | Remove an installed extension |
| `ironclaw ironhub search [query]` | Search the signed IronHub catalog (aliases: `iron-hub`, `hub`) |
| `ironclaw ironhub list` | List available IronHub tools or skills |
| `ironclaw ironhub info <name>` | Show one IronHub catalog entry |
| `ironclaw ironhub install <name>` | Install an IronHub tool or skill |
| `ironclaw skills list` | List configured skills |
| `ironclaw hooks list` | *Not implemented yet* — reports that and exits |
| `ironclaw channels list` | *Not implemented yet* — reports that and exits |
| `ironclaw logs` | *Not implemented yet* — reports that and exits |

Add `--verbose` to `skills list` for extra detail.

Activating an extension that needs credentials starts its setup flow. Complete that from
**Extensions** in the [web interface](/using/webui), which is also where you connect
channels while `channels list` remains unimplemented.

For service logs, read the files directly — see [Run as a Service](/using/service#logs).

---

## Running as a Service

| Command | What it does |
| --- | --- |
| `ironclaw service install` | Install the OS service (launchd or systemd) |
| `ironclaw service start` | Start the installed service |
| `ironclaw service stop` | Stop the running service |
| `ironclaw service restart` | Restart, or start if stopped |
| `ironclaw service status` | Show service status |
| `ironclaw service uninstall` | Remove the service and its unit file |

See [Run as a Service](/using/service).

<Note>
`service` subcommands do not work on a NEAR AI hosted instance — there is no user service
manager for them to drive. Restart a hosted agent from the
[Agent Dashboard](https://agent.near.ai/) instead.
</Note>

---

## Trace Commons

`ironclaw traces` manages optional, redacted contribution of your agent traces. It is off
until you explicitly opt in.

| Command | What it does |
| --- | --- |
| `ironclaw traces status` | Show your current contribution policy |
| `ironclaw traces opt-in` / `opt-out` | Turn contribution on or off |
| `ironclaw traces preview <file>` | Preview a redacted contribution envelope |
| `ironclaw traces submit` / `enqueue` / `flush-queue` | Submit contributions |
| `ironclaw traces queue-status` | Show local queue diagnostics |
| `ironclaw traces credit` | Show credit totals and explanations |
| `ironclaw traces list-submissions` / `revoke` | Review or withdraw past contributions |
| `ironclaw traces enroll-instance` | Enroll an entire instance with an operator invite link |
| `ironclaw traces profile set` / `withdraw` / `token` | Manage the optional public community profile |
| `ironclaw traces ingest-health` | Check an ingestion service health endpoint |

See [Trace Commons](/capabilities/traces).

---

## Shell Completion

| Command | What it does |
| --- | --- |
| `ironclaw completion --shell <shell>` | Print a completion script for `bash`, `zsh`, `fish`, `elvish`, or `powershell` |

```bash
ironclaw completion --shell zsh > "${fpath[1]}/_ironclaw"
```