---
title: "CLI"
description: "Complete reference for the oneie / one command line — 110 commands, auth, API base resolution, JSON output, exit codes and known limits."
type: reference
audience: both
verified: 2026-09-06
canonical: https://one.ie/docs/cli
---
`@oneie/cli` is the operator and agent command line for ONE. It ships two bins, `oneie` and `one`, which are aliases for the same entry point. This page is the complete shipped surface as measured on 2026-09-06.

## Install

```bash
npm i -g @oneie/cli     # installs both bins: oneie and one
npx oneie --help        # run without installing
```

| Package name | Version on npm | Notes |
| --- | --- | --- |
| `@oneie/cli` | 4.0.7 | The scoped package. `npm i -g @oneie/cli`. |
| `oneie` | 4.0.3 | The unscoped mirror. `npx oneie` resolves here, four patch releases behind. |

Runtime dependencies are exactly two: `commander` ^12 and `@oneie/sdk` ^0.14.12.

Licence: the ONE License (Version 1.0), in `LICENSE` in the package. `package.json` declares `SEE LICENSE IN LICENSE`.

## Bare invocation

`oneie` with no arguments prints a front door and exits 0. It branches on audience.

| Condition | Output |
| --- | --- |
| Agent environment | Three lines: `oneie init --write-env`, `oneie onboard`, `oneie --help` |
| Human TTY | The ONE wordmark plus `npx oneie create <name>` and `oneie --help` |

An agent environment is any of `CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_TRACE_ID`, `WINDSURF`, `GITHUB_COPILOT_CLI`, `CI` being set, or `process.stdout.isTTY` being false. Neither branch prompts.

## Zero to live

The shortest path from an empty shell to an authenticated substrate call.

```bash
oneie init --write-env --name "My Agent"  # provision
one whoami                                # prove the key
one ask meta:catalog --data '{}'          # read it back
```

`init` POSTs `/api/provision/agent` with no credential, writes the key to `~/.config/oneie/key` at mode 0600, and with `--write-env` appends `ONE_API_KEY` and `ONE_API_URL` to `./.env.local`. It is idempotent when `--write-env` is set and `ONE_API_KEY` already resolves from `.env`, `.env.local` or the process env. `whoami` exits 1 on a missing or dead key.

The payload flag is `--data <json>`. `--data -` reads the JSON body from stdin. There is no positional payload argument.

## Auth

### Key resolution

There is no single ladder. `resolveKey()` (`src/lib/client.ts:18-24`) is the
canonical one and covers most of the surface:

```
ONE_API_KEY  >  ONEIE_API_KEY  >  ~/.config/oneie/key
```

Five other shapes are in the tree. `--key` is declared on 13 of the 110 leaves,
never on the program, so it is not a global override.

| Ladder | Commands |
| --- | --- |
| `resolveKey()` — the block above | `agent` (19), `broadcast`, `chat`, `connect`, `doctor`, `group`, `links`, `newsletter`, `plugin`, `segment`, `social`, `staff`, `trail`, `whoami`, the 14 substrate commands |
| `ONEIE_API_KEY` > `ONE_API_KEY`. Process env only — no key file, no `--key` | `catalog`, `market`, `hire`, `bounty`, `earn`, `usage`, `recall`, `fn run` |
| `--key` > `ONEIE_API_KEY` > `ONE_API_KEY`, read through `.env` + `.env.local` + the process env — no key file | `client list`, `client add`, `client invite`, `push`, `setup`, `status`, `wallet get\|create\|transactions\|send\|register` |
| `ONEIE_API_KEY` > `~/.config/oneie/key`. `ONE_API_KEY` is never read | `skill import`, `skill fork`, `skill list`, `skill unimport`, `skill eval` |
| `ONE_API_KEY` > `ONEIE_API_KEY`. No key file, no `--key` | `workflow` (7), `skill push` |
| `--key` > `ONEIE_API_KEY`, then the device flow | `auth login`, `login` |

So a shell that exports only `ONE_API_KEY` authenticates `agent` but not
`skill list`; a shell that exports only `ONEIE_API_KEY` authenticates both. The
key file written by `login` / `init` is read by the first and fourth ladders
only — the other four never look at it.

### Bearer form

The header is `Authorization: Bearer <key>` — the plain key. The `<slug>:<key>` form is wrong and 401s: `requireAuth` resolves a world key by its `one-` or `osk_` prefix, so prefixing a slug produces a string that matches no prefix. That form is still printed in `packages/cli/README.md:79` and `text/cli-reference.md:33`. Do not use it.

### Three doors to a key

| Command | Browser needed | Key class | Mechanism |
| --- | --- | --- | --- |
| `one init --write-env` | no | agent | `POST /api/provision/agent`, unauthenticated |
| `one onboard` | no | agent | Same provision call, plus a `lifecycle:mine` stage read-back |
| `one login` | yes | human | RFC 8628 device flow: `POST /api/auth/mcp/device/code`, approval at `https://one.ie/device`, poll `POST /api/auth/mcp/device/token` |

`one setup` also mints an agent-class key through the same provision route.

### The agent-class wall

Keys minted by `init`, `onboard` and `setup` are agent-class. Five receiver labels refuse them at dispatch (`one.ie/web/src/lib/receiver-envelope.ts:151-157`):

```
manage_workspace   manage_clients   manage_members
manage_groups      manage_actors
```

The refusal is not an HTTP error. The receiver door answers **200** with `outcome: "failure"`, and the result object carries `error: "forbidden"`, `forbidden: true`, the receiver name, the required label, and `callerRole: "agent"`. Code that branches on the status line will read it as a success.

The only self-service way past it is `one login`, which mints a human-class key and requires a person at a browser. An agent that cannot get one is capped at the non-management surface.

`one onboard` writes five keys to `.env.local`: `ONE_API_KEY`, `ONE_API_URL`, `ONE_REG_KEY`, `ONE_UID`, `AGENCY_WSID`. Receivers keyed on `ctx.ownerSlug === uid`, including `lifecycle:mine`, need `ONE_REG_KEY`. The workspace-scoped `ONE_API_KEY` resolves to the workspace actor, which has no stage-transition rows, so the call returns nothing rather than erroring.

## The API base

There is no single default. `--api` resolves per command:

```
--api  >  ONE_API_URL  >  ONEIE_BASE_URL  >  module fallback
```

That precedence holds inside `resolveBase()` (`src/lib/client.ts:12-16`). Ten modules bake their `--api` default at module load in the opposite order, and three groups bake a literal, so the env vars do not behave uniformly.

| Commands | Fallback base | Env behaviour |
| --- | --- | --- |
| `chat send`, `chat broadcast`, `connect`, `group`, `social`, `staff`, `trail`, `plugin`, `doctor`, `whoami` | `https://one.ie` | `ONE_API_URL` wins over `ONEIE_BASE_URL` |
| `broadcast`, `segment`, `newsletter`, `links`, and the 14 substrate commands | `https://api.one.ie` | `ONE_API_URL` wins over `ONEIE_BASE_URL` |
| `catalog`, `recall`, `market`, `hire`, `bounty`, `earn`, `usage`, `wallet`, `client`, `push`, `fn` | `https://api.one.ie` | `ONEIE_BASE_URL` wins over `ONE_API_URL` |
| `onboard`, `status` | `https://one.ie` | `ONEIE_BASE_URL` wins over `ONE_API_URL` |
| `auth login`, `auth logout`, `login`, `init` | `https://one.ie` | `ONE_API_URL` ignored; `ONEIE_BASE_URL` honoured |
| `setup`, keyless (the default path) | `https://one.ie` | `--api` **and** `ONE_API_URL` ignored — the provision call reads only `ONEIE_BASE_URL` (`src/setup.ts:54`) |
| `setup`, keyed (a key is already present) | `https://api.one.ie` | `--api`, then `ONEIE_BASE_URL` over `ONE_API_URL` |
| `agent` (19), `skill` (11) | `https://one.ie` | Both env vars ignored; use `--api`. `skill eval` reads `ONEIE_BASE_URL` |
| `workflow` (7) | `https://api.one.ie` | Both env vars ignored; use `--api` |

31 of the 110 leaves declare no `--api` at all; most of those are local (`agent
new`, `skill validate`, `create node`, `ship`, `dev`, `fn list`, …). Three of
them do reach the network, on a different host with their own flag:

| Command | Host | Flag | Env |
| --- | --- | --- | --- |
| `wallet faucet` | `https://pay.one.ie` | `--pay-url` | `ONEIE_PAY_URL` |
| `chat listen` | `https://channels.one.ie` | `--channels` | `CHANNELS_URL` |
| `eval` | `https://channels.one.ie` | `--channels` | `ONEIE_CHANNELS_URL` |

`eval` also takes `--events` for the substrate side, defaulting to
`ONEIE_BASE_URL` and then `https://one.ie`.

### Why the host matters

`api.one.ie` serves substrate operations at the short path form, `/ask/<receiver>`. `one.ie` serves only the long form, `/api/ask/<receiver>`. `src/lib/api-path.ts` picks the form from the hostname, so any command that routes through `askPath()` works against either host.

## Commands

110 leaf commands: 17 groups holding 74 leaves, plus 36 standalone commands. 53 entries appear in `oneie --help`.

### agent (19)

| Command | Does |
| --- | --- |
| `agent new <name>` | Scaffold from a template. `--profile core\|commerce\|asi` |
| `agent validate <path>` | Validate `agent.md` |
| `agent lint <path>` | Lint `agent.md` |
| `agent compile <path>` | Compile. `--target mcp \| uagents \| skillmd \| web`, default `mcp` |
| `agent serve <path>` | Stub. Prints `status=listening` and exits; no server is started (`src/agent.ts:84-90`). `--port 8000` |
| `agent publish <path>` | Publish. `--target oneie\|agentverse`, `--slug`, `--live` |
| `agent pull <name>` | Fetch a published agent to a file |
| `agent unpublish <name>` | Remove a published agent |
| `agent sign <path>` | Sign the agent file |
| `agent verify <path>` | Verify a signature |
| `agent eval <path>` | Run the frontmatter `evals:` block |
| `agent diff <a> <b>` | Diff two agent files |
| `agent dev <path>` | Local dev loop |
| `agent list` | List published agents. `--slug` required |
| `agent history <name>` | Version history. `--slug` required |
| `agent rollback <name>` | Roll back. `--slug` and `--to <epoch-ms>` required, `--yes` |
| `agent ai-edit <path>` | Edit via model. `--prompt`, `--model`, `--yes` |
| `agent templates` | List templates |
| `agent fork <template> <name>` | Copy a template locally |

`a2a` and `erc8004` are not implemented compile targets and fail loudly. The shipped `--target` help names four: `mcp | uagents | skillmd | web`.

See [Agents](/docs/agents) and [Publish an agent](/docs/agents-publish).

### skill (11)

| Command | Does |
| --- | --- |
| `skill new <name>` | Scaffold a skill file |
| `skill emit <path>` | Emit. `--out ./` |
| `skill publish <path>` | Publish a skill |
| `skill refresh <slug> [refs...]` | Refresh imported skills |
| `skill import <ref>` | Import. `--slug`, `--price 0.02`, `--yes` |
| `skill push <path>` | Push to a workspace. `--slug` required, `--name` |
| `skill fork <name>` | Copy an open skill into a workspace. `--slug` required. Refuses sealed, invoke-only skills |
| `skill list` | List workspace skills. `--slug` required |
| `skill unimport <name>` | Remove an imported skill. `--slug` required |
| `skill validate <path>` | Validate a skill file |
| `skill eval <path>` | Run the skill's evals. `--iteration 1` |

See [Skills](/docs/skills).

### workflow (7)

| Command | Does |
| --- | --- |
| `workflow list` | List workflows |
| `workflow pull <id>` | Write the workflow verbatim to `<name>/workflow.json`. `--out <dir>` |
| `workflow push <id> <file>` | Apply a diff file. Simulates by default; `--commit` persists |
| `workflow run <id>` | Start a run |
| `workflow validate <id> <file>` | Validate a diff without persisting |
| `workflow resolve <runId> <stepId>` | Resolve a suspended human step. `--decision approved\|rejected` |
| `workflow logs <id>` | Run history and per-run step events. `--run <runId>`, `--limit` |

Every one of the seven requires `--slug <workspace>`.

`workflow resolve` is the only CLI door into a suspended run. See [Workflows](/docs/workflows).

### wallet (7)

| Command | Does |
| --- | --- |
| `wallet get` | Read balances. `--workspace`, `--actor` |
| `wallet create` | Provision a wallet row. `--kind human\|agent` |
| `wallet transactions` | List transactions. `--limit 100`, max 500 |
| `wallet faucet <address>` | Fund from testnet via `pay.one.ie`. `--chain sui\|sol\|eth\|usdc\|btc\|all` required, `--network testnet\|devnet` |
| `wallet send <to>` | Send crypto. Requires `--chain`, `--amount`, `--payment-tx <hash>`. This command never signs — sign and broadcast client-side first, then pass the hash |
| `wallet register` | Register PUBLIC receiving addresses. First write per chain is permanent; a later write returns `address_conflict`. Prompts unless `--yes` |
| `wallet keygen` | Generate or recover a wallet offline for Sui, EVM, Solana and Bitcoin. `--out <file>` writes the mnemonic and private keys unencrypted at mode 0600 and requires `--yes-i-accept-plaintext-file`. `--recover` reads a 24-word BIP-39 mnemonic from `ONE_WALLET_MNEMONIC` or stdin |

See [Wallets and custody](/docs/wallets).

### client (4)

| Command | Does |
| --- | --- |
| `client new <slug>` | Scaffold a client locally. `--name` |
| `client list` | List clients. Declares its own `--json` |
| `client add <slug>` | Provision a client workspace. `--dry-run` |
| `client invite <email>` | Invite a client owner. `--slug` required, `--dry-run` |

### plugin (4)

| Command | Does |
| --- | --- |
| `plugin list` | List available plugins |
| `plugin add <name>` | Install into a workspace |
| `plugin buy <name>` | Purchase. `--credits` |
| `plugin grant <name>` | Grant to a client. `--to <client>` required |

The program-level `--json` is inert for all four (`src/plugin.ts:6-7` checks the retired `ONEIE_JSON` env var).

### chat (3)

| Command | Does |
| --- | --- |
| `chat send <text>` | Post to a Space. `--to <space>`. This is the group's default subcommand, so `one chat "text"` routes here |
| `chat broadcast <text>` | Fan out to several Spaces. `--spaces <csv>` |
| `chat listen <space>` | Stream inbound messages from `channels.one.ie` |

The built-in `--spaces` default is a fixed list of three space slugs carried over from an internal deployment. It is not a general-purpose default. Pass `--to` or `--spaces` explicitly.

### social (3)

| Command | Does |
| --- | --- |
| `social list` | List posts. `--group <groupId>` required, `--status draft\|scheduled\|publishing\|published\|failed`, `--limit 50` |
| `social create` | Create a post. `--group <groupId>`, `--content` and `--platforms <csv>` all required, `--schedule <epoch>` |
| `social accounts` | List connected accounts |

### create (2)

| Command | Does |
| --- | --- |
| `create node [name]` | Scaffold a workspace. Default subcommand, so `one create my-agency` routes here. `--ref main` |
| `create partner [name]` | Scaffold a partner workspace. `--ref main` |

On a non-TTY, `create` prints directory and launch instructions instead of starting anything.

### fn (2)

| Command | Does |
| --- | --- |
| `fn list` | List the allowlisted functions and their return kinds |
| `fn run <name>` | Execute one. `--args <json>` (keys are prefixed with `$` for you), `--workspace`. Exits 1 on a name outside the allowlist |

### Smaller groups

| Command | Does |
| --- | --- |
| `auth login` | Device flow, or `--key <k>` to store a key directly |
| `auth logout` | Delete `~/.config/oneie/key` |
| `group bulk-create` | Bulk-provision from CSV. `--csv` required, `--segment`, `--plan`, `--parent`, `--batch-size 50`, `--dry-run` |
| `broadcast list` | List broadcasts. `--limit 20` |
| `broadcast send <id>` | Send a broadcast |
| `segment list` | List segments |
| `segment preview <id>` | Preview a segment's members |
| `newsletter pull <broadcastId>` | Pull newsletter content |
| `newsletter push <broadcastId> <file>` | Push content. `--test` |
| `links create <actorId>` | Create a tracked link. `--to /`, `--context`, `--greeting`, `--campaign`, `--expires <days>` |
| `staff invite [email]` | Invite a person. `--role owner\|admin\|member\|viewer`, default `admin` |
| `staff add-agent <name>` | Add an agent as staff. `--role member` |

### Substrate commands (14, standalone)

| Command | Does |
| --- | --- |
| `signal <receiver>` | Fire-and-forget signal. `--data <json\|->` |
| `ask <receiver>` | Request-response. `--data <json\|->`, `--timeout 10000` |
| `mark <edge>` | Strengthen a path. Edge format: `source>target`. `--strength 1` |
| `warn <edge>` | Raise resistance on a path. Edge format: `source>target`. `--strength 1` |
| `fade` | Apply the group fade rate. `--rate <0-1>` |
| `sub <tag> <actor>` | Subscribe an actor to a tag. `--scope private\|public` |
| `follow <type>` | Follow a tag |
| `select <type>` | Weighted selection. `--exploration <0-1>` |
| `groups` | List groups. `--type`, `--limit 20`, `--after <cursor>` |
| `actors` | List actors. `--type`, `--tag`, `--limit`, `--after` |
| `things` | List things. `--type`, `--tag`, `--limit`, `--after` |
| `paths` | List paths. `--source`, `--target`, `--min-strength`, `--limit`, `--after` |
| `events` | List events. `--actor`, `--tag`, `--from <iso>`, `--to <iso>`, `--limit` |
| `learning` | List hypotheses. `--status pending\|testing\|confirmed\|rejected`, `--actor`, `--tag` |

13 of these 14 need an explicit host — see [What does not work yet](#what-does-not-work-yet). `ask` is the exception. Receiver names are listed in [Receivers](/docs/receivers).

### Lifecycle and diagnostics (9, standalone)

| Command | Does |
| --- | --- |
| `init` | Provision a workspace. `--name`, `--email`, `--skills <csv>`, `--no-content`, `--write-env` |
| `onboard` | Provision and walk the lifecycle stages: registered, bootstrapped, active, settled, adopted. `--write-env` defaults to true |
| `login` | Root alias of `auth login`, same implementation |
| `setup` | Provision a workspace and write the key to `./.env.local` (not to `~/.config/oneie/key`). No-op if `ONE_API_KEY` or `AGENCY_WSID`+`CC_ACTOR_ID` are already set. `--key` switches it to the keyed agency flow |
| `doctor` | Three checks — config file, key present, substrate reachable — each under a 5s abort. Exits 0 or 1 |
| `whoami` | Prints workspace, masked key and base. Proves the key with an authenticated `dashboard:usage` call. Exits 1 on a dead key |
| `status` | Billing and client status. Declares its own `--json` |
| `connect [channel]` | Connect a channel with `--token <t>`. With no argument, lists connection status. The token is never echoed back |
| `trail <tags>` | Path trail for a tag set. `--workspace global`, `--limit 10` |

There is no `auth:whoami` receiver. `whoami` proves liveness with `dashboard:usage`.

### Build and ship (5, standalone)

| Command | Does |
| --- | --- |
| `dev` | Local dev server. `-p 8787`, `--ip 127.0.0.1`, `--remote`, `--skip-build`, `--skip-migrate`, `--cwd` |
| `deploy [path]` | Deploy a built site. Default path `site/dist`, `--project <name>` |
| `push [path]` | Push content to a workspace. `--client <slug>`, `--dry-run` |
| `ship [message]` | Stages every untracked and modified file in the working tree, commits with the message, and pushes. See the irreversible-commands table below |
| `eval [path]` | Run `*.eval.ts` through `@oneie/evals`. Default path `evals`. Exits 1 when any eval fails |

### Market and memory (8, standalone)

| Command | Does |
| --- | --- |
| `catalog` | The receiver catalog grouped by recipe. `--goal <text>`. Own `--json` |
| `market` | List the skill market. `--query <text>`. Own `--json` |
| `hire <skillId>` | Hire a peer agent. `--provider <uid>`, `--budget 0`, `--dry-run` |
| `bounty <skillId>` | Post a bounty. `--price 0`, `--dry-run` |
| `earn` | Earnings. Own `--json` |
| `usage` | Metering. Own `--json` |
| `recall` | Cross-session memory. `--about <term>`, `--limit 20`. Own `--json` |
| `reputation` | Registered and reachable. Its own help reads "Agent reputation standing (pending)" and it prints a pending notice — `meta:reputation` is not shipped |

## JSON output

Four tiers, sorted by what the flag actually does. 56 + 4 + 27 + 23 = 110.

| Tier | Count | Behaviour |
| --- | --- | --- |
| 1 | 56 | Honour the program-level `--json` |
| 2 | 4 | Declare and honour their own `--json`, emitting raw JSON rather than the `{ok, …}` envelope |
| 3 | 27 | Emit JSON unconditionally, flag or not |
| 4 | 23 | Never emit JSON |

### Tier 1 — program-level `--json` (56)

Whole groups: `skill` (11), `workflow` (7), `wallet` (7), `social` (3), `auth` (2), `staff` (2) — 32. Plus 18 of the 19 `agent` leaves: every one except `agent dev`, which prints watch output through `console.log` and never reaches the JSON writer.

Six more leaves: `login`, `connect`, `group bulk-create`, `init`, `onboard`, `trail`.

32 + 18 + 6 = 56.

`agent compile` is a half case that belongs here anyway: with `--out <file>` it emits a `{ok, written, bytes}` receipt that honours the flag, but with no `--out` it writes the compiled artifact to stdout raw, so the flag changes nothing.

Flag position does not matter. `jsonMode()` walks `cmd.parent` to the root, so both of these emit one JSON line:

```bash
one agent templates --json
one --json agent templates
```

Without the flag the same command prints `✓ templates=[…]`.

### Tier 2 — own `--json`, honoured (4)

`catalog`, `client list`, `recall`, `status`.

`market`, `earn` and `usage` also declare a `--json` option, but none of the three reads it — they print pretty JSON either way, so they sit in tier 3.

### Tier 3 — always JSON (27)

The 14 substrate commands, `broadcast list`, `broadcast send`, `segment list`, `segment preview`, `newsletter push`, `links create`, `eval`, `market`, `earn`, `usage`, `hire`, `bounty`, `fn run`.

All but `eval` pretty-print with a two-space indent; `eval` writes one compact line. `newsletter push` and the two `--dry-run` trade commands print a human summary line before the JSON.

### Tier 4 — no JSON (23)

`fn list`, `doctor`, `whoami`, `chat send`, `chat broadcast`, `chat listen`, `newsletter pull`, `plugin list`, `plugin add`, `plugin buy`, `plugin grant`, `push`, `setup`, `create node`, `create partner`, `deploy`, `dev`, `ship`, `client new`, `client add`, `client invite`, `reputation`, `agent dev`.

`newsletter pull` prints markdown, not JSON — it is the round-trip half of `newsletter push`. `chat send` is the one leaf here that can emit JSON: given `--to <space>` it prints the raw receiver reply, while the fan-out form prints human lines.

Apart from that, no flag or env var makes these emit JSON.

## Exit codes

Measured 2026-09-06 by running each case unpiped and reading `$?`.

| Case | Code | Stream |
| --- | --- | --- |
| Success | 0 | stdout |
| `--help`, `--version`, bare `oneie` | 0 | stdout |
| Unknown command | 1 | stderr |
| Missing required option | 1 | stderr |
| `{ok:false}` from a tier-1 command | 1 | `error  <msg>` on stderr; under `--json`, the object on stdout |
| Substrate command, non-2xx response | 1 | `METHOD url → status` then the body on stderr, then exit |
| `fn run` with a name outside the allowlist | 1 | stderr |
| `doctor` with any failing check | 1 | check lines on stdout |
| `whoami` with a missing or dead key | 1 | stderr / stdout |
| `eval` with any failing eval | 1 | stdout |
| Unhandled error, no `--json` | 1 | message on stderr |
| Unhandled error, `--json` anywhere in argv | 1 | `{"ok":false,"error":"…"}` on stdout |

`ship` propagates the exit status of the underlying commands, except that a commit returning 1 (nothing to commit) is not treated as a failure.

## Reading a refusal

| Status | Meaning | Fix |
| --- | --- | --- |
| 401 | The Bearer matched no `world_keys` row — wrong key, or not a key | Check the key ladder; send the plain key, not `<slug>:<key>` |
| 403 | The key is real and the authority walk refused it for that workspace | Use a key that owns the workspace, or a human-class key for a management label |
| 404 on `api.one.ie/api/*` | Wrong path form for that host | Pass `--api https://one.ie` |

On the receiver door the same split reads as `callerRole: "anonymous"` versus any other role. See [Authority and access](/docs/authority) and [Errors and limits](/docs/errors).

## Environment variables

| Variable | Read by |
| --- | --- |
| `ONE_API_KEY` | Key, canonical. Not read at all by the `skill import\|fork\|list\|unimport\|eval` ladder — see [Key resolution](#key-resolution) |
| `ONEIE_API_KEY` | Key, legacy. The only variable every key ladder reads |
| `ONE_API_URL` | Base, canonical. See the per-module table above |
| `ONEIE_BASE_URL` | Base, legacy. `ONE_BASE_URL` is retired |
| `ONE_REG_KEY`, `ONE_UID`, `AGENCY_WSID` | Written by `onboard`; `ONE_REG_KEY` is needed by uid-scoped receivers |
| `AGENCY_SLUG` | Default `--workspace` for `wallet` |
| `ONEIE_WORKSPACE` | Default `--workspace` for `plugin` |
| `CHANNELS_URL`, `ONEIE_CHANNELS_URL` | `chat listen`, `eval` |
| `ONEIE_PAY_URL` | `wallet faucet` |
| `ONE_WALLET_MNEMONIC` | `wallet keygen --recover` |
| `AGENTVERSE_API_KEY`, `ANTHROPIC_API_KEY` | `agent publish --target agentverse` |
| `GROQ_API_KEY` | `eval` |
| `WORKSPACE_OWNER_EMAIL`, `WORKSPACE_ID`, `WORKSPACE_SLUG`, `AGENCY_NAME`, `CC_ACTOR_ID` | `src/env.ts` merge |
| `ONEIE_JSON` | Retired everywhere except `plugin`, where it is still the only JSON switch |
| `CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_TRACE_ID`, `WINDSURF`, `GITHUB_COPILOT_CLI`, `CI` | Agent-environment detection |

`.env` and `.env.local` are merged in that order, and `process.env` overrides both.

## Commands that change things irreversibly

| Command | What it does |
| --- | --- |
| `ship` | Runs `add -A`, then a commit, then a push, as git child processes in the current working directory (`src/ship.ts`). It stages every untracked and modified file in the tree, including work it did not create. A shell-level git guard does not see it, because it is a child process rather than a shell string |
| `wallet register` | Writes public receiving addresses to a workspace. First write per chain is permanent; a later write returns `address_conflict`. There is no undo. It prints the exact addresses and prompts unless `--yes` |
| `wallet keygen --out <file>` | Writes the mnemonic and every private key to disk unencrypted at mode 0600. Refuses without `--yes-i-accept-plaintext-file` |

## What does not work yet

**14 commands 404 against their own default host.** The 13 substrate commands other than `ask` — `signal`, `mark`, `warn`, `fade`, `sub`, `follow`, `select`, `groups`, `actors`, `things`, `paths`, `events`, `learning` — plus `fn run` build the long `/api/*` path while defaulting to `https://api.one.ie`, which serves only the short form. Measured:

```bash
$ one things --limit 1
GET https://api.one.ie/api/things?limit=1 → 404
{"error":"Not found"}

$ one things --limit 1 --api https://one.ie
{ "things": [ { "id": "shape:do:feature", … } ], "total": 1 }
```

The fix is `--api https://one.ie` on the command, or `ONE_API_URL=https://one.ie` in the environment. Both are verified working. `ONE_API_URL` is the broader move: it also repoints every other command that reads it, though not `workflow`, `agent` or `skill`, which bake a literal host and answer only to `--api`.

**`agent compile --target a2a` and `--target erc8004` are not implemented** and fail loudly. Four targets ship: `mcp`, `uagents`, `skillmd`, `web`.

**`agent publish --target agentverse` forwards `ANTHROPIC_API_KEY`** to a third-party host, announced by variable name on stderr. The injected `ONEIE_API_KEY` is not yet consumed by the generated agent, and it has not been verified that the Agentverse sandbox permits importing the Anthropic client.

**`one eval` degrades outside the monorepo.** `@oneie/evals` is a devDependency, deliberately not bundled, because shipping it as a runtime dependency broke `npm i -g`. It is published — `npm view @oneie/evals version` returns 0.1.1 — so `npm i -g @oneie/evals` alongside the CLI is a real fix; the package's own source comment calling it unpublished is stale. From a global install without it, the command returns `{ok:false, error:"The \`eval\` command needs the @oneie/evals package, which is not bundled in the published CLI…"}`.

**`one reputation` is a stub.** It is registered and reachable and prints a pending notice; `meta:reputation` is not shipped.

**`agent serve` is a stub.** It checks the path exists, prints `status=listening`, and exits. No port is bound and no A2A or MCP server starts.

**`--json` is inert for `plugin`.** All four verbs read the retired `ONEIE_JSON` env var instead, because no call site passes the command object.

**Two published files carry wrong statements about this package.** `packages/cli/README.md:79` and `text/cli-reference.md:33` both give the Bearer token as `<slug>:<key>`, which 401s. `README.md` also closes with an MIT licence line; the shipped licence is the ONE License v1.0, and the MIT claim is wrong. `README.md` further shows a positional payload after the receiver name — the flag is `--data`.

**The two npm names are not published in lockstep.** `oneie` is 4.0.3, `@oneie/cli` is 4.0.7. `npx oneie` runs the older one.