One Horizon CLI

Website · Docs · Support

one is the command-line client for One Horizon.

Use it to manage One Horizon work from the terminal, open tasks in a coding app, or have Codex work through assigned tasks. You can sign in, switch workspaces, list work, inspect task details, update status, comment, and launch supported tools from the same shell.

Why Use It

• Work with One Horizon from bash or zsh on macOS and Linux.
• Check tasks, bugs, and initiatives without opening the dashboard.
• Save your preferred coding tools and folders per workspace.
• Send work to supported coding apps with prompts built from the task itself.
• Let Codex work through assigned tasks, then comment and hand the result back for review.
• Keep small updates fast when you are already in the terminal.

Install

Install the package globally with your preferred package manager:

npm install -g @onehorizon/cli

pnpm add -g @onehorizon/cli

yarn global add @onehorizon/cli

Yarn 4 and later removed yarn global. Use npm or pnpm for a global install, or run without installing:

yarn dlx @onehorizon/cli --help

You can also try it without a global install:

npx @onehorizon/cli --help

After installation, the CLI is available as:

one --help

Update

Use the same command you used to install:

npm install -g @onehorizon/cli

pnpm update -g @onehorizon/cli

yarn global upgrade @onehorizon/cli

On Yarn 4 and later, re-run the install via npm or pnpm.

Uninstall

npm uninstall -g @onehorizon/cli

pnpm remove -g @onehorizon/cli

yarn global remove @onehorizon/cli

On Yarn 4 and later, uninstall via whichever package manager you used to install.

Local config, saved tokens, and worker task workspaces are stored in ~/.one/config/. Remove that directory to clean up all CLI data:

rm -rf ~/.one/config

Requirements

• A One Horizon account with access to at least one workspace.
• Node.js 20 or newer.
• On Linux, a working Secret Service setup if you want secure local token storage.

Quick Start

Sign in, confirm your workspace, then list your current work:

one auth login
one ws
one dashboard
one list

Pick a coding tool, save a folder, then send a task to that tool:

one settings tools add codex
one settings folder add ~/Sites/myproject
one send tsk_123 --tool codex --mode code

Create a worker when you want Codex to work through assigned tasks. During creation, press Enter to use WORKFLOW.md, the recommended workflow file name:

one worker create
one worker doctor
one worker watch

Common task updates:

one show tsk_123
one start tsk_123
one comment tsk_123 "Investigated the callback flow"
one close tsk_123

Commands

Every command supports --help. Use one <command> --help or one <command> <subcommand> --help for details.

Authentication

one auth login
one auth status
one auth logout

one auth login opens your browser and completes sign-in with PKCE. If the CLI cannot open your browser, it prints the sign-in URL so you can open it yourself.

Workspaces

one ws
one ws list
one ws use <name-or-id>
one dashboard [workspace-id]

On an interactive terminal, one ws opens a picker over your available workspaces. Use ↑ and ↓ to move, Enter to choose, and Esc or Ctrl+C to cancel.

one dashboard opens the active workspace in your browser. Pass a workspace ID if you want to open a different workspace without changing your saved default.

Listing Work

one list
one ls
one ready
one blocked

one list defaults to your open, planned, and in-progress work.

Useful options:

-t, --type <initiative|bug|task>
-s, --status <status>
-T, --team <name-or-id>
--all
--page <n>

Supported statuses:

• open
• planned
• in_progress
• in_review
• blocked
• completed
• idea
• cancelled
• merged

one ready focuses on planned, in-progress, and in-review items that do not have blocked upstream dependencies in the current task graph.

Task Actions

one show <id>
one create [title] [options]
one start <id>
one close <id>
one block <id>
one reopen <id>
one status <id> <status>
one comment <id> [text]

Create options:

-t, --type <task|bug|initiative>
-d, --description <text>
-T, --team <name-or-id>
-a, --assignee <name-or-id>

one create [title] and one comment <id> [text] accept inline text, piped stdin, or an interactive prompt.

When run interactively without flags, one create walks through type, title, description, team, and assignee prompts in order. It ends with a review screen where you can press Enter to create, e to edit a specific field, or Ctrl+C to cancel. If you belong to a single team it is auto-selected; if you belong to multiple, a team picker appears. Assignee selection is offered after the team is chosen and filters to members and admins of that team, with you as the default.

If you omit the task ID for show, start, close, block, reopen, or status, the CLI opens a task picker over active work. Each option shows the task ID, title, type, and status. Use ↑ and ↓ to move, Enter to choose, and Esc or Ctrl+C to cancel.

Settings

one settings
one settings tools list
one settings tools add [tool]
one settings tools remove <tool>
one settings folder list
one settings folder add <path>
one settings folder remove <path>

one settings shows the current workspace settings and prints the next commands to add, remove, or list tools and folders.

one settings tools add without an argument opens an interactive picker on a TTY. Pass a tool name directly to skip the prompt.

Supported coding tools:

• codex
• cursor
• windsurf
• claude_code
• open_code

The CLI can launch all five tools directly from the terminal. claude_code and open_code are launched as a shell process — they take over the current terminal session. codex, cursor, and windsurf are launched via their app URL scheme. If you have saved terminal folders, the first one is used as the working directory for shell-launched tools.

Folders are stored per workspace. Use absolute paths or ~/... paths. Home-directory paths are normalized so they stay consistent across sessions.

Send To App

one send [id]

Useful options:

--tool <tool>
--mode <plan|code|review|fix>
-t, --type <type>
-s, --status <status>
-T, --team <team>
--all
--page <n>

How it works:

• one send <id> fetches the task in the active workspace.
• If the task stores its body in a document, the CLI pulls that content before building the prompt.
• If you do not pass --tool or --mode, the CLI prompts for them in an interactive terminal.
• If you run one send without an id in a TTY, the CLI lets you choose from a filtered task list.
• After a successful launch, the CLI tries to tag the task with the selected coding tool.
• claude_code and open_code spawn the claude / opencode binary directly and take over the current terminal session. The one process resumes and tags the task once the session ends.

Interactive send follows the same controls: ↑ and ↓ to move, Enter to choose, Esc or Ctrl+C to cancel.

Worker

Use the worker for tasks you would normally hand to Codex with the same instructions every time: small bug fixes, scoped features, dependency updates, docs changes, and cleanup work with clear acceptance criteria.

The worker is not a chat surface. One Horizon provides the task; your workflow file tells Codex how to prepare the repo, which checks to run, when to commit, and how to hand the result back for review.

Codex runs in a workspace-write sandbox with network access enabled so workflow setup, installs, tests, and handoff steps can use the repo’s normal tools.

Common use cases:

• Let Codex pick up queued local agent sessions for your worker while you keep working elsewhere.
• Run a single task first to create and claim one local agent session before trusting the workflow loop.
• Keep setup, test, commit, and handoff rules in the repo instead of in local notes.
• Split repo runbooks by task type, such as backend work, docs updates, or release chores.

Create it:

1. Run one worker create.
2. Choose the default agent. Use codex for the built-in worker path.
3. Create a starter workflow file. Press Enter to accept WORKFLOW.md, or type another filename if this repo needs more than one workflow.
4. Choose how the worker prepares the workspace: a git worktree per task, or this repo folder with a task branch. Worktrees are the safer default for automatic pickup.
5. Edit the workflow file with your test command, commit rules, push command, and PR instructions.
6. Run one worker doctor to check auth, config, the workflow file, the workspace root, and the Codex command.

Worker creation registers a new One Horizon server worker with a generated two-word bot name, such as Cherry bot or Hamburger drone. You can rename it later from the Agents screen.

one worker create stores local runtime settings in two places:

• ~/.one/config/worker-config.json keeps the active/default worker for older CLI versions.
• ~/.one/config/workers/<workspace-id>/<worker-id>/config.json stores machine-specific runtime settings for a specific One Horizon worker.

One Horizon is the source of truth for which workers exist and where task worktrees are created. The local per-worker config only says whether this machine knows how to run that server worker: repo path, workflow path, worktree mode, runtime limits, PID, state, and logs.

If the active workspace has multiple server workers, watch and start choose from those workers only. Server workers missing local runtime settings are shown as not configured on this machine, and running background workers are shown as already running; neither can be selected. one worker doctor reports stale local runtime configs that no longer have a matching server worker.

Run work:

one worker run <task-id>
one worker watch
one worker start
one worker remove
one worker worktrees

one worker run <task-id> creates a local agent session for one task, claims it, runs the workflow, and exits. Start here when you are testing a new workflow.

one worker watch heartbeats a configured local worker, polls queued sessions visible to that worker, claims one session at a time, and prints progress in the current terminal. Requires one worker create or one worker configure first.

one worker start runs the same worker in the background. Manage it with one worker status, one worker logs, and one worker stop.

Use one worker watch --worker <worker-id> or one worker start --worker <worker-id> when you already know which active-workspace worker to run.

one worker status shows the background worker state and queued work it can see. When multiple server workers exist in the active workspace, it summarizes them by default; use one worker status --worker <worker-id> for detailed progress and queued pickup for one worker.

one worker remove stops the configured worker if needed, removes its One Horizon registration, and deletes its local config. Past runs stay available.

If a worker is removed from the web app while this machine is offline, the local runtime config becomes stale. Normal worker lists ignore it; one worker doctor reports it with a cleanup hint.

By default, a registered worker polls queued agent sessions and claims work through One Horizon before Codex starts. Legacy task polling can still act as a fallback when agent worker registration is unavailable; in that path, tracker.active_states controls which task statuses are eligible.

The starter WORKFLOW.md includes repo setup hooks:

• Worktree mode creates an isolated git worktree under .one/worktrees by default before Codex starts.
• Repository mode runs Codex in the selected repo folder and checks out worker/<task-id>. Keep max concurrency at 1 for this mode.
• Commit and PR instructions require task-specific titles instead of generic Completed task titles.

Clean up task worktrees when they start taking space:

one worker worktrees
one worker worktrees remove tsk_123
one worker worktrees remove --all
one worker worktrees --workflow WORKFLOW.backend.md

Remove refuses dirty worktrees unless you pass --force.

Use a different workflow file when one repo needs more than one runbook:

one worker run <task-id> --workflow WORKFLOW.docs.md
one worker watch --workflow WORKFLOW.backend.md
one worker start --workflow WORKFLOW.release.md

Troubleshooting:

| Problem | What to check | | --- | --- | | watch or start says no worker has been created | Run one worker create in the active workspace to register a new server worker and save local runtime settings for this machine. | | watch or start says the worker is not configured on this machine | A server worker exists but this machine has no local runtime settings for it. Run one worker configure to bind this machine to the existing worker without creating another one. | | The worker does not pick up work | Confirm a queued local agent session exists for your worker and workspace. If the worker is using legacy fallback, confirm the task matches tracker.active_states. | | doctor cannot find the workflow file | Run the command from the repo folder, rerun one worker create, or pass the file directly with --workflow WORKFLOW.backend.md. | | Codex starts in an empty workspace | Check the generated hooks in WORKFLOW.md. Worktree setup should happen in hooks.after_create; repository mode uses hooks.before_run. | | one worker status says no worker is running | status only tracks background runs started with one worker start. Foreground watch runs report in their own terminal. If the active workspace has multiple server workers, pass --worker <worker-id>. | | Worker worktrees use too much disk space | Run one worker worktrees to list them, then remove one task worktree or pass --all. | | A task gets stuck or fails repeatedly | Run one worker logs, inspect the configured task workspace, then make the setup or test instructions more explicit. |

Examples

List planned work for a team:

one list --status planned --team Platform

Open the current workspace in your browser:

one dashboard

Open a different workspace by ID:

one dashboard ws_123

List all blocked bugs:

one list --type bug --status blocked --all

Create a bug:

one create "Fix login bug" --type bug --description "OAuth callback returns 400"

Create a task and let the CLI prompt for the title:

one create --type task

Pipe a note from another command:

printf 'Investigated the callback flow' | one comment tsk_123

Save a tool and send a task to it:

one settings tools add codex
one send tsk_123 --tool codex --mode code

Browse interactively and pick a task to send:

one send --status planned --team Platform

Local Storage

The CLI stores local state such as the selected workspace on disk. Tokens are stored outside the plain config file and use platform secure storage where available.

On Linux, secure token storage depends on the local Secret Service setup.

Troubleshooting

The Browser Did Not Open

Run one auth login again and open the printed URL manually in your browser.

Sign-In Timed Out

The CLI waits for the browser callback for up to two minutes. Start one auth login again and finish the browser step before the timeout.

My Session Expired

Run:

one auth login

Linux Token Storage Is Unavailable

Make sure your desktop session has Secret Service support and that secret-tool is installed and available on your PATH.

one send Tells Me To Configure A Tool

Add a supported launchable tool first:

one settings tools add codex

You can also add cursor, windsurf, claude_code, or open_code. claude_code requires the claude binary to be installed and on your PATH.

I Do Not See Any Workspaces

Your account may not have access to a workspace yet. Ask your workspace admin to add you, then run one auth login again.

License

@onehorizon/cli is licensed under Apache 2.0.

That gives downstream users a standard permissive open-source license with an explicit patent grant. The full license text is included in this package in LICENSE.

The license applies to the package source and bundled CLI code. It does not grant rights to use the One Horizon name, logo, or hosted service beyond normal descriptive use.