Coding agent CLI
Connect a computer, authenticate Pi providers, register repositories, and manage the BernOps host.
On this page
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.
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.
For Playwright and native SDK execution capacity, use Connect a worker. 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:
/absolute/verified/bootstrap-linux-x64/install.sh
export PATH="$HOME/.local/bin:$PATH"
bernops --versionThe 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:
bernops setup- 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.
- Complete platform login, then separately approve the linked personal host. If both components are selected, worker workspace approval is another independent grant.
- 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. - 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:
./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:
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.
Agent-led delivery MVP (restricted candidate)
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.
- 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.
- 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.
- 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.
- 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, 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:
./dev.sh install-cli
./dev.sh up
bernops service upgrade
BERNOPS_AGENT_DELIVERY_ENABLED=true bernops service installThese 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 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,pausedormanual_attentionalone 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:orboard: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:
bernops --json workspace list
bernops --debug statusGlobal 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
bernops auth login
bernops auth login --target local
bernops auth statusThese 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:
bernops provider login openai-codex
bernops provider statusFollow 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.
bernops provider logout openai-codexFor your own inference infrastructure, see 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, 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:
bernops repo add "$PWD"
bernops repo listBoth 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.
bernops service status
bernops service logs --lines 200For remote approvals and an agent that must remain available after logout:
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:
bernops service upgrade
bernops service rollbackThese 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:
bernops service uninstall
bernops setup --components agentHost 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.
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 rotateSearch the current public documentation without logging in, configuring a provider, or installing the coding-agent component:
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-referenceThe 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. Public references do not guarantee that those operations are available in your deployed backend or installed host.
Choose the right logout
bernops auth logoutrevokes this installation's remote CLI session, then clears local OAuth state.bernops auth logout --local-onlyclears only the local OAuth credential.bernops logoutdestructively removes local host identity/outbox state and its service, not remote host authorization. It is not a lock or reset repair.bernops provider logoutremoves only the selected model-provider credential.bernops disconnect --everythingcleans 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 reportsremote_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, verifyhttp://127.0.0.1:3410/healthwhen using--target local.- No browser: add
--no-browserand 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 setupwith 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_unconfiguredorcomponent_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.