One Horizon CLI
Use the CLI to work from your terminal. The one command can sign in, choose a workspace, list work, open details, create updates, send work to coding tools, and run the local Codex worker.
Common paths
| Goal | Command |
|---|---|
| Set up the CLI | one auth login, then one ws use |
| List and inspect work | one list, one show <id> |
| Create or update work | one create, one comment, one status |
| Send one item to a coding tool | one send <id> |
| Run queued Codex work locally | Local Workers |
Install
You need Node.js 20 or newer. Install the CLI globally with npm or pnpm:
npm install -g @onehorizon/clipnpm add -g @onehorizon/cliCheck the installation:
one --helpYou can also run the CLI without a global install:
npx @onehorizon/cli --helpyarn dlx @onehorizon/cli --helpUpdates follow the same package manager you used to install.
Sign in
Run:
one auth loginThe command starts a browser-based OAuth flow with PKCE. If the browser does not open, the CLI prints a URL you can open yourself.
Useful auth commands:
one auth statusshows the active session.one auth logoutclears the session.
Local state is stored under ~/.one/config/; tokens use platform secure storage when the operating system supports it.
If the browser does not open during one auth login, copy and open the printed URL yourself. The login callback waits for a short time, then exits if no callback arrives.
Choose a workspace
Pick the workspace the CLI should use:
one ws use <name-or-id>Other workspace commands:
one wsopens an interactive workspace picker.one ws listprints workspaces you can access.one dashboardopens the active workspace in the browser.one dashboard <workspace-id>opens a specific workspace.
The CLI follows the same workspace and launch preferences you configure in the dashboard. That keeps terminal workflows aligned with your default workspace, selected coding tools, and saved project folders.
API keys
The CLI uses OAuth for its own requests. Use API Keys when a backend service, CI job, or trusted script needs workspace-scoped API access.
API key list, create, and revoke operations are REST API operations. Use the API Keys page for setup guidance and the API reference for exact requests.
List and update work
Use one list or one ls to see open, planned, and in-progress work. Use one ready for unblocked items in planned, in progress, or review. Use one blocked to focus on blocked work.
Open one item:
one show <id>Create work with one create. Move work through the lifecycle with:
one start <id>one close <id>one block <id>one reopen <id>one status <id> <status>
Add context with one comment. It accepts inline text, stdin, or an interactive prompt.
If you omit a task ID in an interactive terminal, commands open a picker for the work they can act on. one reopen only lists completed, cancelled, or merged work.
Send work to coding tools
Use one send [id] to launch one work item in a coding tool. The CLI builds a prompt from the record, including document-backed descriptions when present, then opens the tool you choose.
Modes include Plan, Code, Review, and Fix. You can pass --tool and --mode, or pick them interactively.
Supported launch targets include Codex, Cursor, Windsurf, Claude Code, OpenCode, and Conductor. Codex, Cursor, and Windsurf use app URL schemes. Claude Code and OpenCode run as shell processes and use the saved terminal folder when you have configured one.
After a successful launch, the CLI tries to add the coding tool to the record's taxonomy. For the product flow behind this command, see Use in Terminal.
Configure launch settings
one settings shows workspace-specific coding tools and folders for the active workspace.
one settings tools add codexone settings folder add ~/Sites/project
Use one settings tools list and one settings folder list to inspect the active workspace settings.
Run a local worker
Use the Codex worker when work should queue for a local worker on your machine.
The worker is experimental. Prefer small tasks and bug fixes over large rewrites or major initiatives, and review code, tests, and pull requests before you merge or ship.
Quick path:
one worker setupone worker doctorone worker run tsk_123
Use one worker watch for a foreground worker. Use one worker start for a background worker, then manage it with:
one worker statusone worker logsone worker stop
Worker setup creates or reuses a server worker for the active workspace and signed-in user, then saves local runtime settings under ~/.one/config/.
Use Local Workers for the user workflow and Agent Sessions for the execution model.
Uninstall
Remove the package with the package manager you used:
npm uninstall -g @onehorizon/clipnpm remove -g @onehorizon/cliyarn global remove @onehorizon/cliOn Yarn 4 or later, use npm or pnpm.
The uninstall command removes the binary but leaves local configuration. To remove auth state, saved folders, tools, and worker configs:
one auth logoutrm -rf ~/.one/config
If you have both ~/.one/config/ and ~/.config/one/, remove both when you want a clean machine state.