# Coding agent CLI

Connect a computer, authenticate Pi providers, register repositories, and manage the BernOps host.

Use the BernOps CLI to connect this computer to the app and run creator-owned coding sessions with the bundled Pi agent. A personal coding-agent host is separate from a workspace execution worker.

**The short version**

Install the approved private bootstrap, then run `bernops setup` from the repository you want to authorize. Choose **2 (coding agent)** or **4 (both)**. The menu defaults to **1 (platform authentication only)**, which does not connect a host.


**Need a worker instead?**

For Playwright and native SDK execution capacity, use [Connect a worker](/docs/workers-and-pool#worker-setup). Run `bernops setup` and choose **3 (automation worker)**, or **4 (both)** for independent host and worker setup. The wizard handles shared platform login and separate workspace worker approval. Worker-only selection does not install Pi or configure a provider. `bernops auth login` is auth-only and never enrolls a host or worker.


## Quick start

Distribution remains private: there is no supported public download URL, `curl | sh`, or npm install name. Obtain the complete approved bootstrap archive from your operator and authenticate its checksum and provenance through a trusted channel **before extraction or execution**. A checksum beside an untrusted download does not establish trust.

After approved retrieval and extraction, run the included installer as your regular user, without sudo. Replace the example path with the verified extraction path:

```bash
/absolute/verified/bootstrap-linux-x64/install.sh
export PATH="$HOME/.local/bin:$PATH"
bernops --version
```

The bootstrap includes pinned Node 22.19.0; end users do not install Node, NVM, or build the CLI from source. Its intended scope is Ubuntu/Debian x86-64; fresh desktop/headless OS and cloud production qualification remain incomplete. The operator must configure approved signed component releases. Auth-only needs no Pi, Docker, or worker runtime.

From the Git repository you want to authorize, run:

```bash
bernops setup
```

1. Choose **2 (coding agent)** or **4 (both)**, not the auth-only default. Select the displayed current Git root or enter another absolute Git-root path. The repository name is generated automatically without a naming prompt. Detection alone does not grant access.
2. Complete platform login, then separately approve the linked personal host. If both components are selected, worker workspace approval is another independent grant.
3. Setup installs the signed private agent component, handles OpenAI Codex login when local credentials are absent, and configures repository access and the user service. Compatible provider credentials are reused. No preliminary `auth login`, manual provider login, or upgrade command is required.
4. Wait for the selected components to report `ready`. Agent readiness requires available repository access, provider credentials, an active user service, and an observed authenticated host connection, not just a running process. This does not issue a billable model request to validate the provider.

For development from the approved BernOps checkout against the local stack:

```bash
./dev.sh install-cli
bernops setup --local
```

`./dev.sh install-cli` prepares signed local releases and activates the local-target private bootstrap without restarting the stack. It can use an already-installed NVM Node 22.19.0, but never installs NVM or Node. Release preparation has developer build prerequisites; it is not the end-user installation path. The local backend must be running with its release catalog configured.

Setup and `auth login` default to **cloud**, regardless of the build, saved identity or setup journal. Use `bernops setup --local` (or `--target local`) for local development; use `--target cloud` for an explicit cloud choice. Target conflicts fail rather than migrating identities, and viewing these docs locally does not select a CLI target. An inference server on localhost does not select a local BernOps backend.

For explicit selection instead of the interactive menu:

```bash
bernops setup --components agent --repo /home/user/code/project
```

`--repo <directory>` selects an absolute Git-root path without a naming option. Without a TTY, including JSON mode, `--components` is required: `auth`, `agent`, `worker`, or `agent,worker`. Do not combine `auth` with other names; authentication is already shared. Explicit flags do not remove approval or provider interactions.

Pi is the built-in runtime. Do not pass `--runtime`, `--backend`, or `--app`; those are not public onboarding options.

For personal token statistics, model breakdowns and the daily heatmap, see [Usage analytics](/docs/agent-tools#usage-analytics).

## Agent-led delivery MVP (restricted candidate)

**Qualification is not rollout permission**

Delivery remains default-off and requires a compatible, explicitly approved host. Component and provider-free worker-only checks do not qualify agent/both activation or authentic model delivery. Real-provider trials, measured model routing/costs and live remote permission trials remain unqualified when skipped. Independent feature and human acceptance, merge and rollout are separate gates. This guidance neither enables the feature nor guarantees unattended correctness.


1. In project **Agents → configurations**, select creator-private implementation and review configuration revisions. Review provider/model, thinking, instructions, allowed tools and limits. Managed delivery allows 1–128 tool calls and 5–240 wall minutes per attempt; parallel members count individually, waits count toward elapsed time, and Task/TaskBatch are disabled. These limits are not an aggregate spend cap or proof that a process stopped.
2. Open **Workflows → New run** (the **Configure run** tab), select label, host, repository, target ref and both configurations, then preview the complete snapshot. Inspect excluded items, external predecessors, blocker paths and execution order. Work must be unclaimed Todo, not Backlog. The graph cannot infer missing semantic dependencies: check declarations before acknowledging them, even when no dependencies are shown. Resolve blockers before Start; changed scope/config revisions require another preview and approval.
3. Start freezes the approved scope and role settings. Its receipt means admission, not successful execution. Reconcile an uncertain Start using the explicit same-request action, never a new retry key. Implementation claims one item, checks and pushes the delivery branch before In Review. A fresh review-and-repair session fetches the newest branch, makes substantial in-scope repairs when needed, checks and pushes before Done. Honest no-ops need evidence, not invented commits. Dependent work waits for Done, required receipts and positive predecessor stop; manually moving cards does not prove readiness.
4. One retained worktree/branch and one accumulating PR serve the run. Final review checks the cumulative newest head, including reviewer repairs. Consequential final fixes require one fresh exact-head checks-only verification, not another repair loop. The final handoff is for human review: Done, awaiting human and completed do not mean merged or deployed. Only the human decides merge separately from rollout.

The workflow detail view shows canonical state/revision/generation, writer release, attention reason, next actor, sessions, branch/PR and control history. Closing the browser does not cancel the backend run; refresh on return. Ledger verdicts, reported heads and check references are agent assertions: inspect the artifacts and actual remote/board effects. Requested model is distinct from observed model. Usage is paginated; absent tokens or cost are **unknown**, not zero. Catalog costs are estimates, not provider invoices or a total-run budget.

### Workflow dashboard and read-only examples

Open **Workflows** directly from the left project sidebar, below Agents. The link retains the selected project and stays active on run-detail pages. The **Workflows → Overview** tab separates supervision from launch. Filter private runs by Active, Needs attention, Awaiting review or Finished, and search their frozen work-item titles, branch or run ID. Run titles come from the first item in execution order, not a separately saved workflow name. Last successful refresh means the last server read, not the last agent activity; failed reads retain a stale-data warning.

Open a run to inspect its outcome and next action. **Execution history** groups implementation and review under each frozen task title, with cumulative final review separate. Earlier attempts stay inside their stage; the current or failed stage opens for inspection. **Frozen requirements and dependencies** preserves the approved scope without crowding the execution history. An awaiting-human run points to **Review pull request**, not a still-running final stage; it is not merged.

Each stage separates **Report**, **Model & usage** and **Technical details**. Open its conversation or PR directly. Check references are expandable agent reports, never independent certification. **Board: Done** comes from a separate current board read, not a reported-ready badge; failed or unavailable board reads remain unknown. Writer release describes the current allocation at workflow level, not a per-stage claim inferred from readiness. Semantic colors reinforce text and icons: green for current board Done or confirmed release, blue for active execution, amber for waiting/intervention and red for failed/blocked stages. Agent-reported readiness stays neutral.

Usage loads only when **Model & usage** is opened. **Recorded usage** is explicitly the retained observations on the current page—not whole-stage or whole-workflow totals. Missing tokens or costs remain unknown, never zero. Primary and child requests retain separate attribution; multiple observed models remain visible. Configured/requested models and copyable IDs/commits are under **Technical details**. Catalog cost estimates, including zero, are not invoices or proof of free execution. Retrieve this guide with `bernops docs search "execution history"` and `bernops docs get coding-agent-cli#workflow-supervision`.

Revision/generation and control history remain under **Advanced diagnostics and control history**. Manual recovery fields appear only when recovery is relevant; the explicit proof/recheck rules below still apply.

The **Examples** tab offers six read-only scenarios: ready to launch, blocked scope, running, needs attention, paused and awaiting human review. Each says **Demo example — no agent executed**. Examples are presentation data only: they do not populate your account, create board tasks, connect a host, call a provider, operate on Git or submit lifecycle controls. Their proposed checkout-validation, accessible-form and browser-check requirements describe a small disposable-repository lab, not a real execution result. A real trial still requires an approved compatible host, provider/spend and disposable remote with externally enforced push/merge restrictions. The examples neither enable delivery nor replace authentic acceptance.

### Local delivery runtime opt-in (operators only)

Retrieve this section with `bernops docs search BERNOPS_AGENT_DELIVERY_ENABLED` or `bernops docs get coding-agent-cli#delivery-local-opt-in`.

This restricted developer switch is **default-off**, not production rollout or proof of successful delivery. Obtain task-scoped approval for the non-production machine and its CLI/service changes first. Keep normal [local setup](#quick-start), native credentials, explicit provider selection and remote permission boundaries; a separate worktree is not a sandbox.

With no active managed run and an idle host, preserve `backend/.env.local` and set `BERNOPS_DELIVERY_ENABLED=true` there without replacing its other settings. The backend requires `BERNOPS_ENVIRONMENT=development` and local HTTP Supabase API/public URLs on port `54421`; other targets fail startup. Use the reviewed frontend-dev Compose override through `dev.sh`, not a base-only backend recreation:

```bash
./dev.sh install-cli
./dev.sh up
bernops service upgrade
BERNOPS_AGENT_DELIVERY_ENABLED=true bernops service install
```

These commands replace the approved local CLI, refresh the local stack without reset, select the current signed release volume and restart the idle agent. Existing local authentication/host approval must be valid; otherwise use `bernops setup --local`, never no-flag setup as a local test. The host opt-in requires Linux, the real Pi runtime and the exact backend `http://127.0.0.1:3410`. It persists through supported service operations; an ambient shell flag on status, restart or ordinary upgrade does not change it. Real runtime initialization must provide preparation, execution and recovery consumers before advertising `delivery_sessions_v1`, `delivery_preparation_v1` and `delivery_recovery_v1`. Do not patch capability rows to bypass admission.

Inspect the connected host, refresh the canonical UI preview and approve Start once. A `201` receipt only proves admission. If execution is blocked, retain the run and exact failure; do not substitute a chat session or manually advance cards.

To disable after all managed work has settled, run `BERNOPS_AGENT_DELIVERY_ENABLED=false bernops service install`, set the backend switch to `false` and run `./dev.sh up` without reset. Disable before rolling back to a release predating this switch. Toggling configuration is not Cancel or positive writer-stop evidence; use [manual recovery](#delivery-recovery) for active work.

### Pause, Cancel and manual Resume

- **Pause** drains/fences progression; it is not rollback or instant termination. A committed handoff may drain. An early Pause before preparation exists may be rejected without writes; reread the run.
- **Cancel** requests abort/close, not deletion of pushed effects. `cancel_requested`, `paused` or `manual_attention` alone never proves the old writer stopped or the reservation was released.
- **Resume** is manual reconciliation, then positive release proof and a later explicit admission. Inspect the old processes/journals and reconcile push, PR and board effects first. Enter the observed 40-character lowercase head SHA and honest effect statuses; unknown is not “none”. Reconciled effects need matching `push:`, `pr:` or `board:` artifact references (at most 12 refs). Preserve the saved attestation/recovery identity while explicitly rechecking pending proof with fresh server state. A pending response is not resumed execution.
- If a control response is uncertain, use only the exact-original-request reconciliation. Do not replace identities or retry automatically. After a definitive recovery rejection, investigate before deliberately using the offered new-attestation action. Missing proof, revocation or an uncertain old writer requires operator attention, not a second run.

Never delete locks, journals, retained reservations or receipts, force another owner off work, or move cards to bypass writer exclusion. Worktrees are **not sandboxes**: tools and children inherit the host user's filesystem/network permissions and privilege policy. BernOps does not provide execution isolation or grant sudo. Operators must enforce external credentials and protected-target denial of push/merge/auto-merge; prompt instructions are not branch protection.

PR-feedback restart, automatic merge/recovery/replay and parallel delivery writers are deferred. Preserve failures and interrupted attempts with exact candidate/head and safe evidence references, without secrets. Repository operators should use `docs/agent-led-delivery-runbook.md` and `docs/test-vm-workflow.md`: integration/installed CLI tests belong in the exclusively owned approved guest, never the stable/source installation or production. Provider-free qualification marks unrun model branches SKIPPED, not PASS, and does not remove the product's provider requirements for agent sessions.

## Chat code and retrieved sources

On supporting releases, chat code and diffs use shared Code Block controls; tools, reasoning and subagents use Trace presentation. Copy preserves the original text, including a plain-text fallback for unsupported syntax. Changed-file summaries offer an optional folder view without changing diff or omission details.

Successful web tools can display bounded **retrieved sources**, including safe links, excerpts, retrieval time and an omission notice. Retrieval time is not publication time. Link previews describe explicit links in the reply; neither retrieved sources nor previews prove that a source supports a particular claim. No claim-level citations are inferred.

Deploy the metadata migration before the supporting backend. Metadata is negotiated: old hosts and existing browser tabs continue without it; refresh to enable the new display. New hosts suppress metadata for unsupported backends. If a backend is downgraded after enriched events were journaled, those events remain pending until support returns; they are never rewritten under an existing event identity. This documentation does not imply production deployment or authorize upgrading a protected installation.

## Readable and JSON output

Interactive terminals show concise human-readable results. Pipes and redirected commands keep the stable compact JSON format for scripts. Use a leading `--json` flag to force that format, or a leading `--debug` flag to add redacted technical details to interactive output:

```bash
bernops --json workspace list
bernops --debug status
```

Global output flags must precede the command. Combining `--json` and `--debug` produces only the normal JSON envelope, without an extra stream that could break parsing. Debug output never adds OAuth tokens, project API keys, pairing secrets, request bodies, or raw unknown errors. Human and debug views redact returned claim lease tokens, so claim automation that needs them must use `--json`. `bernops service logs` remains an unformatted log stream.

## User login and credential storage

```bash
bernops auth login
bernops auth login --target local
bernops auth status
```

These are **auth-only alternatives**, not prerequisites for setup. `bernops auth login` creates or reuses only the platform user session: it does not enroll a host, log in to Codex, register repositories, or start a service or worker. Use `bernops setup --components auth` for the same lightweight selection through the wizard; pass `--target local` or `--target cloud` when choosing an auth target explicitly.

Linux Secret Service is the default for **both local and cloud** platform credentials. It needs `secret-tool`, `gdbus`, and an unlocked Secret Service in the actual user's D-Bus session. Access tokens remain memory-only. There is no automatic plaintext fallback. For a new identity, `--credential-store file` or explicit `BERNOPS_AUTH_STORE=file` accepts an owner-only **unencrypted** refresh-credential file. Saved identities retain their store; this option is not a migration command. Repair locked, denied, or unavailable native storage rather than downgrading it.

Workspace, project, job, queue, run, and discovery commands use this OAuth user session. `bernops app` remains explicitly authenticated by a project API key; neither principal silently falls back to the other.

## Provider login

Agent selection in `bernops setup` already handles OpenAI Codex login when needed, using pinned Pi provider infrastructure. Unified onboarding currently supports only `openai-codex`; auth-only and worker-only selection do not configure a provider. For later inspection or deliberate provider reauthentication on an installed agent:

```bash
bernops provider login openai-codex
bernops provider status
```

Follow the provider's printed login instructions. `--no-browser` does not guarantee noninteractive provider login; a non-TTY run can report `provider_login_interactive_required`. Credentials stay in `~/.pi/agent/auth.json` and are never sent to the BernOps backend.

```bash
bernops provider logout openai-codex
```

For your own inference infrastructure, see [OpenAI-compatible providers](/docs/openai-compatible-providers): connect local Ollama, Strata or another compatible API with explicit Bearer or keyless authentication, then select its model manually. The guide includes local Strata and remote authenticated examples, a [custom-provider-only host path without Codex](/docs/openai-compatible-providers#without-codex), UI selection and troubleshooting. These commands require a supporting installed release and do not change the standard setup wizard's Codex policy.

## Register repositories

The wizard can register a repository with your consent. Only explicitly registered checkouts can be selected in BernOps. To add another Git root later, run from that root:

```bash
bernops repo add "$PWD"
bernops repo list
```

Both registration commands name repositories automatically from the basename of the Git `origin` repository. HTTPS (`https://github.com/owner/project.git`), SSH URL (`ssh://git@github.com/owner/project.git`), and scp-style (`git@github.com:owner/project.git`) origins all yield `project`, with the trailing `.git` removed. If no usable origin name is available, the canonical checkout folder's basename is used instead. There is no naming prompt or custom alias/label option.

Optional `bernops repo add <directory> --remote owner/name` supplies only the existing safe remote metadata; it does not override the generated name. The wire/storage fields `alias` and `display_name` remain unchanged. The app receives safe repository metadata and availability, not the host's canonical path. Keeping existing access adds no cwd or home-directory access. An agent with no available registered repository reports attention, not readiness. Registration is not an OS sandbox: the personal agent inherits your user's permissions.

## Background service and headless use

Unified agent setup requires a regular non-root user and a working systemd user manager. It installs the service if absent, starts it if stopped, and preserves a verified running service. Missing manager or required linger returns attention, **not a foreground fallback**. Ask the administrator to review the user D-Bus/session configuration; setup never installs system packages or changes privileged settings.

Agent service staging still runs `npm ci` with bundled npm and requires dependency registry access. Signed archive delivery does not make service installation offline.

```bash
bernops service status
bernops service logs --lines 200
```

For remote approvals and an agent that must remain available after logout:

```bash
bernops setup --components agent --repo /home/user/code/project \
  --no-browser --headless
```

`--no-browser` suppresses browser launch, not consent. Leave the CLI polling, open each printed URL on another device, compare the human code and signed-in account, and review the host fingerprint before approving. Platform approval uses an Authorization Code + PKCE relay, not an OAuth device grant. Keep approval URLs and codes private.

`--headless` is agent-specific and requires `loginctl show-user "$UID" --property=Linger --value` to report `yes`. An administrator may review enabling linger for that user; setup never enables it. Headless does not imply file storage: use native storage when available, or deliberately add `--credential-store file` for a new identity if you accept unencrypted storage.

The advanced `bernops --foreground` command remains available for deliberate foreground operation of an installed agent. It is not the unified setup path and does not satisfy its background-service readiness checks.

## Upgrade

Rerun `bernops setup` with the same target and selections to resume or check readiness. Selecting fewer components never uninstalls existing ones. Interactive setup asks before selecting a changed signed agent release or updating an eligible idle service that lacks connection-status support. Declining, busy work, or failed verification preserves state and reports attention; no manual upgrade is required for the normal interactive path.

For deliberate service lifecycle operations on an installed agent:

```bash
bernops service upgrade
bernops service rollback
```

These deliberately restart the service using verified releases and retained rollback state. They do not update the bootstrap or migrate accounts, targets, or origins. Do not delete or edit release receipts or `installation.json` to force an upgrade.

To deliberately remove only the service, then let agent setup install it again:

```bash
bernops service uninstall
bernops setup --components agent
```

Host identity, repositories, Pi credentials, releases, and session data remain preserved by service uninstall. The private bootstrap installer is not a self-updater and rejects an existing command; ask the operator to review replacements. For a development checkout, `./dev.sh install-cli` can activate a verified local bootstrap while preserving recovery material.

## Command shortcuts

Choose the command for your intent; this list is not a sequence to run. Logout and disconnect are deliberate cleanup operations, not setup prerequisites.

```bash
bernops setup
bernops setup --target local
bernops setup --local
bernops setup --components auth
bernops setup --components agent,worker
bernops auth login
bernops auth login --target local
bernops auth login --credential-store file
bernops auth status
bernops auth logout
bernops auth logout --local-only
bernops logout
bernops disconnect --everything
bernops status
bernops doctor
bernops provider login openai-codex
bernops provider status
bernops repo add <directory>
bernops repo list
bernops service status
bernops service restart
bernops credential rotate
```

Search the current public documentation without logging in, configuring a provider, or installing the coding-agent component:

```bash
bernops docs search "worker setup"
bernops --json docs search "work item claims" --limit 10
bernops docs search "variables" --locale fr
bernops docs get coding-agent-cli#command-reference
```

The CLI fetches a compact index from `https://bernops.com` over HTTPS and returns matching section links and short excerpts. It does not download every page or send your query to a search provider. Public docs describe their current revision; check installed `--help` for commands supported by an older CLI.

For operation discovery, managed compact reads, safe ETags and atomic roadmap planning on supporting versions, see [Efficient agent tools](/docs/agent-tools). Public references do not guarantee that those operations are available in your deployed backend or installed host.

## Choose the right logout

- `bernops auth logout` revokes this installation's remote CLI session, then clears local OAuth state.
- `bernops auth logout --local-only` clears only the local OAuth credential.
- `bernops logout` destructively removes local host identity/outbox state and its service, not remote host authorization. It is not a lock or reset repair.
- `bernops provider logout` removes only the selected model-provider credential.
- `bernops disconnect --everything` cleans up local auth, host, and service state, plus credentials for the default OpenAI Codex provider only, not all stored providers. It does not remove or uninstall workers and performs no remote revocation; the result reports `remote_revoked:false`.

Platform logout does not remove host, provider, or worker access. Browser logout, whole-client grant revocation, server-side host revocation, project API-key revocation, and session deletion remain separate actions. Installed read/cleanup commands such as `status`, `doctor`, `service stop|logs|status|uninstall`, `repo list`, and `provider status|logout` can use the verified signed installed runtime without live platform login or release access. This is not an offline installation or execution bypass.

## Troubleshooting

- `backend_unreachable`: from the same network namespace, verify `http://127.0.0.1:3410/health` when using `--target local`.
- No browser: add `--no-browser` and use the printed verification URL while the CLI keeps polling.
- Native vault unavailable or locked: restore the keyring/session. File storage requires explicit acceptance for a new identity and cannot migrate a saved native session.
- Account mismatch: finish with the account that owns the offered host, or cancel and start a new transaction. BernOps never transfers the host.
- No models: run `bernops provider status`, then log in to the required provider.
- No systemd user manager or missing headless linger: ask the administrator to provision the prerequisites, then rerun setup. There is no automatic foreground fallback.
- Database reset or verified retired local host: rerun `bernops setup` with the same target and selections. Review **Reconnect this PC?** when offered. Explicit consent can archive retired local sessions and obtain fresh host approval while retaining provider login and repository access. Do not delete state or use logout as a universal repair.
- `component_release_trust_unconfigured` or `component_releases_not_configured`: ask the operator for an approved bootstrap and signed release catalog. Do not bypass signatures or install public substitutes.
- Interrupted setup: stop concurrent operations, confirm the original process has exited, then rerun the same choices. Secure setup locks can reclaim verified stale owners; unsafe/live locks need operator investigation, not blind deletion.

The summary reports `ready`, `needs_attention`, `failed`, or `not_selected` per component. Exit 0 means all selected components are ready, 2 means attention, and 1 means failure. Completed components remain intact if another fails.

See the repository's `docs/unified-onboarding.md` and `cli/README.md` for the full onboarding contract, release gates, and operator recovery procedures.
