One Horizon CLI
The one command brings workspace work into your terminal: list and update work, send it to coding tools, and run local agents.
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 agent work locally | Run agents from the terminal |
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. After you update the CLI, the next one command restarts background agents started with one agent start.
Sign in
Run:
one auth loginThe command starts a browser-based OAuth flow with PKCE. one auth status shows the active session and one auth logout clears it.
Local state is stored under ~/.one/; bearer tokens use platform secure storage when the operating system supports it.
If the browser does not open, 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 uses:
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 workspace, coding tool, and project folder preferences you configure in the dashboard.
API keys
The CLI uses OAuth for its own requests. API Keys are for backend services, CI jobs, and trusted scripts. Listing, creating, and revoking keys are REST API operations; see the API reference.
List and update work
one list (or one ls) shows open, planned, and in-progress work. one ready shows unblocked items in planned, in progress, or review, and one blocked shows 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
one send [id] launches one work item in a coding tool. The CLI builds a prompt from the initiative, bug, or todo, including document-backed descriptions, then opens the tool you choose.
Modes are plan, code, review, research, and fix (for bugs). 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 item's taxonomy.
Configure launch settings
one settings shows the coding tools and folders saved for the active workspace. one settings tools list and one settings folder list print them. Add a tool or folder:
one settings tools add codexone settings folder add ~/Sites/project
Run a local agent
A local agent picks up queued work on your machine. Run agents from the terminal covers one agent create, doctor checks, background pickup, logs, and worktree cleanup.
Uninstall
Remove the package with the same package manager you used to install it:
npm uninstall -g @onehorizon/clipnpm remove -g @onehorizon/cliyarn global remove @onehorizon/cliOn Yarn 4 or later, use npm or pnpm.
Uninstalling leaves local files. To remove auth state, saved folders, tools, and agent configs:
one auth logoutrm -rf ~/.one