One Horizon CLI
Use the One Horizon CLI to work from your terminal. The one command can sign in, choose a workspace, list work, open details, create updates, send tasks 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 worker quickstart |
Installing
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.
Uninstalling
Pick the command for your package manager:
npm uninstall -g @onehorizon/clipnpm remove -g @onehorizon/cliyarn global remove @onehorizon/cliOn Yarn 4 or later, use npm or pnpm.
Remove local files
The uninstall command removes the binary but leaves config files on disk. Sign out first to clear your token from OS secure storage, then delete the config directory:
one auth logoutrm -rf ~/.one/config
~/.one/config/ holds auth state, the active workspace, saved tools and folders, and any worker configs from one worker setup. Skip this step if you plan to reinstall.
If you have both ~/.one/config/ and ~/.config/one/ on this machine, delete both.
Signing 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 OS 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.
Choosing 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.
Listing 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>In an interactive terminal, omitting the id opens a task picker. List commands accept filters for type, status, team, workspace-wide views, and pagination.
Creating and updating
one create starts a guided flow for tasks, bugs, and initiatives. It asks for the type, title, description, team, assignee, and final review before saving.
Move work through the lifecycle:
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.
Picking tasks faster
If you omit a task id, interactive commands only list actionable work and order it for the command you ran.
one reopen only lists completed, cancelled, or merged tasks.
one reopen is for closed work only. Use one status or one start if the task is still active.
Sending to coding tools
Use one send [id] to launch one task in a coding tool. The CLI builds a prompt from the task, including document-backed descriptions when present, and opens the tool you choose.
Modes include Plan, Code, Review, and Fix. You can pass --tool and --mode, or pick them from the prompt when they are missing. After a successful launch, the CLI tries to tag the task with the coding tool you used.
Supported launch targets include Codex, Cursor, Windsurf, Claude Code, and OpenCode. Codex, Cursor, and Windsurf use their app URL schemes. Claude Code and OpenCode run as shell processes and use your saved terminal folder as the working directory when you configured one.
If you use Claude Code, install One Horizon Desktop so the one:// launch link resolves on your machine. See Claude Code for setup details.
You can also read Codex, Cursor, and Windsurf for tool-specific notes.
Configuring settings
one settings shows workspace-specific coding tools and folders for the active workspace. Use one settings tool add <tool> and one settings folder add <path> to maintain the same launch targets used by the dashboard agent launcher flow.
Running the Codex worker
Use the Codex worker when you want One Horizon to queue work and let a local worker pick it up on your machine. Use it for work you do not want to launch one item at a time with one send.
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
For setup, watch mode, background mode, status, logs, stop, and troubleshooting, use the CLI path in the local worker quickstart. See Codex for how Codex fits into One Horizon outside the worker.