Coding agent CLI

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.

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

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:

./dev.sh install-cli
bernops setup

./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 uses an explicit target when supplied; otherwise it checks saved user identity, then the setup journal, then the bootstrap's compiled default. Local bootstraps default to local; general builds default to cloud, without implying a public release. bernops setup --target local is available for an explicit local choice. Target conflicts fail rather than migrating identities, and viewing these docs locally does not select a CLI target.

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.

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

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:

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.

bernops provider logout openai-codex

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 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://[email protected]/owner/project.git), and scp-style ([email protected]: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 200

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

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.

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:

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