npm package: @onehorizon/cli
Description: Use One Horizon from the terminal
Latest version: 0.2.8

# One Horizon CLI

[Website](https://onehorizon.ai) · [Docs](https://onehorizon.ai/docs) · [Support](https://join.slack.com/t/onecommunitycrew/shared_invite/zt-3pfndy2wy-IMkk146kt4Zw72kLp6R~6g)

`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:

```bash
npm install -g @onehorizon/cli
```

```bash
pnpm add -g @onehorizon/cli
```

```bash
yarn global add @onehorizon/cli
```

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

```bash
yarn dlx @onehorizon/cli --help
```

You can also try it without a global install:

```bash
npx @onehorizon/cli --help
```

After installation, the CLI is available as:

```bash
one --help
```

## Update

Use the same command you used to install:

```bash
npm install -g @onehorizon/cli
```

```bash
pnpm update -g @onehorizon/cli
```

```bash
yarn global upgrade @onehorizon/cli
```

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

## Uninstall

```bash
npm uninstall -g @onehorizon/cli
```

```bash
pnpm remove -g @onehorizon/cli
```

```bash
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:

```bash
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:

```bash
one auth login
one ws
one dashboard
one list
```

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

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

Common task updates:

```bash
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

```bash
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

```bash
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

```bash
one list
one ls
one ready
one blocked
```

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

Useful options:

```text
-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

```bash
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:

```text
-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

```bash
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

```bash
one send [id]
```

Useful options:

```text
--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:

```bash
one list --status planned --team Platform
```

Open the current workspace in your browser:

```bash
one dashboard
```

Open a different workspace by ID:

```bash
one dashboard ws_123
```

List all blocked bugs:

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

Create a bug:

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

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

```bash
one create --type task
```

Pipe a note from another command:

```bash
printf 'Investigated the callback flow' | one comment tsk_123
```

Save a tool and send a task to it:

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

Browse interactively and pick a task to send:

```bash
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:

```bash
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:

```bash
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.