Run agents from the terminal

The One Horizon CLI can configure and run a local agent without Desktop. You need Node.js 20 or newer, Git, a writable repository, and access to the workspace that owns the work.

1. 1

   Install the CLI

   Install the package globally, then verify the command.

   npm install -g @onehorizon/clione --help

2. 2

   Authenticate

   Run one auth login. Complete the browser OAuth flow, or open the printed URL yourself when the browser does not open. Confirm the session with one auth status.

3. 3

   Select the workspace

   Run one ws use <name-or-id>, or run one ws to choose interactively. Agent registration and queued work use this active workspace.

4. 4

   Create and configure the agent

   From the repository, run one agent create. Choose Codex, Claude Code, Cursor, or Mistral Vibe; a compatible preset; agent access; the workflow file; PR/MR behavior; and code isolation. Run one agent configure --agent-id <agent-id> only when an existing server-side agent has no local configuration on this machine.

5. 5

   Check the setup

   Run one agent doctor. Resolve any authentication, workspace, repository, workflow file, runtime, or worktree error before starting execution.

6. 6

   Start and verify

   Run one agent watch for foreground pickup or one agent start for background pickup. Use one agent status to confirm the agent is online and inspect queued work, local execution capacity, backpressure, and resource pressure.

Provider and folder preferences are shared with the dashboard, even though Desktop is not required to operate the CLI.

The Preferences screen shows the coding tools and terminal folders used by direct one send launches.

Runtime requirements

The provider choice determines which executable and authentication state the runtime checks during setup and doctor.

Claude Code, Cursor, and OpenCode own their CLI authentication and sandbox behavior. One Horizon stores agent settings, but it does not store provider credentials.

OpenCode is managed through the runtime catalog. Run one runtime list to inspect its setup state, one runtime update opencode to review and enable the curated runtime, then one agent create --runtime opencode to create the agent.

Agent commands

Command	Behavior
one agent run <taskId>	Runs one known work item immediately, waits for the terminal outcome, then exits. It does not upload visual artifacts yet.
one agent watch	Polls for assigned work in the foreground and prints progress. Stop it with Ctrl+C.
one agent start	Starts background pickup for the configured agent.
one agent status	Shows background process state, queued work, completed counts, token totals, local execution capacity, backpressure, and resources.
one agent logs	Prints recent agent logs and follows new output until Ctrl+C.
one agent stop	Requests a server-side stop, shuts down the local background process, and marks the agent offline.
one agent remove	Removes the configured local agent after confirmation.

With several local agents in the active workspace, pass --agent-id <agent-id> to watch, start, status, or doctor where supported. Foreground watch prints its own status; status primarily tracks agents started in the background.

Worktree cleanup

Task worktrees default to ~/.one/worktrees. To store them elsewhere on this machine, set worktreesDir in ~/.one/config/local.json (for example D:\\OneHorizon\\worktrees on Windows). Existing agents that still use the implicit default pick up the new path automatically; per-agent overrides in worker.json stay authoritative.

Command	Behavior
one agent worktrees	Lists agent-managed worktrees and disk usage.
one agent worktrees remove <task-or-path>	Removes one managed worktree when it is safe to do so.
one agent worktrees remove --all	Removes all safe managed worktrees.
one agent worktrees remove <task-or-path> --force	Discards local changes while removing one worktree.

Inspect the worktree and preserve any branch or uncommitted change you still need before forcing removal.

Automatic cleanup can leave a worktree in place when the task worktree or repository root has uncommitted changes, or when branch handoff fails. Resolve the Git state first, then run the cleanup command again.

For every CLI command and workspace operation outside agent execution, see the CLI reference. Local agents explains runtime presets, access, ownership, settings, restart behavior, and what happens during a run.