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

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.

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 and Publish an agent.

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.

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.

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.

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. ask is the exception. Receiver names are listed in 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:

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 and Errors and limits.

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
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:

$ 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.