One Horizon CLI

Website · Docs · Support

one is the command-line client for One Horizon.

It lets you manage work from the terminal, then hand a task off to a coding app without bouncing back to the browser. You can sign in, switch workspaces, list work, inspect task details, update status, leave comments, and launch supported coding tools from the same shell session.

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.
• 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 and saved tokens are stored in ~/.config/one/. Remove that directory to clean up all CLI data:

rm -rf ~/.config/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

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.

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.