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.

After you update the CLI, the next one command restarts background agents started with one agent start. Foreground one agent watch sessions must be restarted manually.

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, agent runtime state, and agent task workspaces are stored under ~/.one/. Bearer tokens live in the OS secret store. Remove ~/.one/ to clean up local CLI and agent files:

rm -rf ~/.one

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 an agent when you want Codex or Claude Code to work through assigned tasks. During creation, press Enter to use WORKFLOW.md, the recommended workflow file name:

one agent create
one agent doctor
one agent 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.

Agent

Use the agent 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 agent is not a chat surface. One Horizon provides the task; your workflow file tells the local agent how to prepare the repo, which checks to run, when to commit, and how to hand the result back for review.

Codex and Claude Code agents use the selected runtime preset and agent access level. Code and Review default to Workspace access, Plan defaults to Read-only, and Full access is available as an explicit host-trust choice. Network access follows the agent policy so workflow setup, installs, tests, and handoff steps can use the repo’s normal tools when policy allows it.

Common use cases:

• Let Codex pick up queued local agent sessions for your agent 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 agent create.
2. Choose the agent. Codex and Claude Code are both available. Claude Code requires a local claude binary on your PATH and an authenticated Claude Code CLI session.
3. Choose a runtime preset: Code, Plan, or Review.
4. Choose agent access: Read-only, Workspace access, or Full access.
5. Create a starter workflow file. Press Enter to accept WORKFLOW.md, or type another filename if this repo needs more than one workflow.
6. Choose how the agent prepares the workspace: a git worktree per task, or this repo folder with a task branch. Worktrees are the safer default for automatic pickup.
7. Edit the workflow file with your test command, commit rules, push command, and PR instructions.
8. Run one agent doctor to check auth, config, the workflow file, the workspace root, and the agent command.

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

one agent create keeps setup choices in memory until One Horizon returns a concrete server agent. It then writes typed local state:

Local config under ~/.one/config/ stores the active local agent reference, machine-specific settings such as projectRoot and workspaceRoot, and per-agent auth metadata. Bearer tokens stay in the OS secret store.

One Horizon is the source of truth for which agents exist and for portable runtime behavior. The local per-agent config only says whether this machine knows how to run that server agent: repo path, worktree root, local runtime limits, PID, state, and logs.

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

Run work:

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

one agent 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 agent watch heartbeats a configured local agent, polls queued sessions visible to that agent, claims one session at a time, and prints progress in the current terminal. Requires one agent create or one agent configure first.

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

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

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

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

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

By default, a registered agent polls queued agent sessions and claims work through One Horizon before Codex starts. Legacy task polling can still act as a fallback when agent 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 agent/<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 agent worktrees
one agent worktrees remove tsk_123
one agent worktrees remove --all
one agent 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 agent run <task-id> --workflow WORKFLOW.docs.md
one agent watch --workflow WORKFLOW.backend.md
one agent start --workflow WORKFLOW.release.md

Troubleshooting:

| Problem | What to check | | --- | --- | | watch or start says no agent has been created | Run one agent create in the active workspace to register a new server agent and save local runtime settings for this machine. | | watch or start says the agent is not configured on this machine | A server agent exists but this machine has no local runtime settings for it. Run one agent configure to bind this machine to the existing agent without creating another one. | | The agent does not pick up work | Confirm a queued local agent session exists for your agent and workspace. If the agent 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 agent 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 agent status says no agent is running | status only tracks background runs started with one agent start. Foreground watch runs report in their own terminal. If the active workspace has multiple server agents, pass --agent-id <agent-id>. | | Agent worktrees use too much disk space | Run one agent worktrees to list them, then remove one task worktree or pass --all. | | A task gets stuck or fails repeatedly | Run one agent 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.