CLI reference

Commands and local connection state

Accepted command forms, option values, authorization boundaries, support labels, and local state locations.

Use this reference when you know which operation you need. The diagnostic guide helps you choose an operation when the failure is still unclear.

01 / CLI reference

Read the examples against your installed release

Obtain the approved setup package from the administrator. Release availability is deployment-specific. A source build does not establish that a package has been published.

Use npx @betterloop/setup for initial package invocation. The shorter betterloop command applies when your approved installation provides it.

Substitute HARNESS with claude-code, codex, or mimir. Substitute PATH with an existing local repository. Enclose a path containing spaces in quotes.

PROJECT_ID names a configured knowledge project. KEY names an approved MCP server. UUID names an existing optimization candidate. These examples do not create identifiers.

Read resource identities and pinned versions from the connected catalog. Obtain learning entry and session identifiers from the applicable existing exposure.

Check the available options and installed setup release before relying on a feature.

npx @betterloop/setup --help
npx @betterloop/setup --version

In verify, the double dash separates Betterloop options from the selected program and its arguments. The command runs locally.

Choose a check that evaluates the intended result. A passing unrelated program supplies no evidence that the task or learning entry worked.

02 / CLI reference

Device and repository operations

Device and repository operations
Accepted command form	Reason to run it	Effect
setup --harness HARNESS	Create a device connection or add an agent	Enrolls or resumes authorization and enables the selected agent integration.
status	Read the current device connection	Inspects state without modifying it.
doctor --harness HARNESS --project PATH	Inspect a specific agent and repository	Reads diagnostic evidence without modifying the connection.
sync --harness HARNESS --project PATH	Obtain signed content or retry preparation	Refreshes rules and learning, retries bounded events, and reports control coverage.
forget --harness HARNESS --project PATH	Rebuild the cache for one repository	Archives that cache while preserving enrolled-device authorization.
uninstall --harness HARNESS	Stop managing one selected agent	Removes owned integration state and revokes the agent’s restricted credentials.
disconnect	Leave the enrolled organization/team connection	Revokes device authorization and disables all managed integrations.

Setup repeats the harness flag. Doctor inspects one selected agent and repository at a time.

betterloop setup --harness claude-code --harness codex
betterloop doctor --harness codex --project /path/to/repository

Uninstall retains the native agent, its provider credentials, and unrelated plugins. Disconnect affects the entire device connection. Choose the intended scope.

A revoked enrollment cannot reconnect through cached credentials. When authorization has been revoked, obtain fresh enrollment rather than reusing an archive.

Explicit older-workflow options

Use --migrate when intentionally converting an existing runtime connection. The first migration needs fresh device enrollment and a matching legacy team.

Use --legacy only when intentionally retaining repository enrollment. Device enrollment is the default setup path. These flags select different workflows.

03 / CLI reference

Options and environment inputs

Options and environment inputs
Option	Value	Interpretation
--harness	claude-code, codex, mimir	Selects an agent. Setup repeats the flag; library commands accept comma-separated agent names.
--project	Local repository path	Identifies session context while leaving enrollment scoped to the device.
--knowledge-project	Configured project identifier	Chooses the intended knowledge match during setup or sync when several matches exist.
--api-url	Deployment URL	Selects the deployment endpoint. HTTPS is required except for loopback development.
--json	No value	Requests machine-readable results from commands that support this option.
--yes	No value	Accepts installation of a missing agent. Native sign-in and trust still require completion.
--account	codex, claude-code, cursor, api	Selects the Mimir account route. Native subscription integration and API access remain separate.
--provider	openai, anthropic	Chooses the provider when using the Mimir API-key route.

Options and environment inputs
Environment variable	Purpose	Required handling
BETTERLOOP_ENROLLMENT_CODE	Personal code for unattended device setup	Load through the process environment. Exclude the value from source files and shell history.
BETTERLOOP_PROVIDER_API_KEY	Provider secret for Mimir API access	Select --account api and --provider. Setup transfers the secret through stdin.
BETTERLOOP_API_URL	Endpoint for a private deployment	Use the deployment owner’s supplied URL.
BETTERLOOP_HOME	Separate local state location for tests	A different directory does not create authorization or restore a revoked connection.

Use the approved secret-loading method for sensitive values. Exclude secrets from command examples and shared diagnostics. Keep them out of repository files.

Provider subscription access does not produce an API key. Confirm that the chosen authentication route is available in your deployment.

04 / CLI reference

Optional resource selection

Optional resource selection
Command form	Local result	Reading the result
library browser	Opens a read-only catalog session lasting ten minutes	Prepared installation commands still require execution on the connected device.
library list	Lists approved resources available for selection	Availability alone does not establish installation on any selected agent.
library show ID	Displays the selected catalog record	Read its version, files, instructions, and dependency identities.
library install ID --version VERSION --harness AGENTS	Installs an approved pinned selection locally	Required organization and team resources remain binding.
library update ID --version VERSION --harness AGENTS	Changes the explicitly selected pinned version	The selection does not track a mutable latest version.
library uninstall ID --harness AGENTS	Removes a developer-selected optional resource	Required team selections are unaffected by this operation.
library status	Reports local selections for each agent	Selection state cannot establish later use or execution.

Substitute the catalog-approved identity and exact version for these illustrative values.

betterloop library show org.review
betterloop library install org.review --version 1.0.0 --harness claude-code,codex
betterloop library status

The signed optional manifest binds each selection to the team release and reviewed organization revision. Clients validate scope, expiry, digests, and dependencies.

Missing, expired, revoked, or unsupported selections are disabled. Revocations survive sync. A developer selection cannot reverse a shared revocation.

Successful selections remain when another agent fails. Repair the failed agent’s installation, authentication, or trust. Repeat the operation only for that agent.

05 / CLI reference

MCP account authorization

MCP expands to Model Context Protocol. A reviewed connection definition identifies the server that supplies external tools or resources.

Definition installation, account authorization, tool permission, and verified discovery are distinct results. Completing provider sign-in does not authorize all available tools.

Use the approved KEY and select the agent whose server authorization you intend to manage.

betterloop mcp-auth-status --harness codex --server KEY
betterloop mcp-login --harness codex --server KEY
betterloop mcp-logout --harness codex --server KEY

Approved macOS OAuth connections store tokens in Keychain through the shared Betterloop proxy. A Keychain failure does not trigger plaintext token storage.

A changed endpoint, issuer, resource, or approved scope invalidates authorization reuse. Complete the required authorization for the changed connection before repeating discovery.

New Linux OAuth and Windows device setup or OAuth remain deferred. Existing supported Linux behavior does not imply those deferred additions are available.

06 / CLI reference

Optimization and contribution operations

Optimization and contribution operations
Command form	Local purpose	Sharing or publication effect
optimize --harness HARNESS --action list	Find existing private candidates	Discovery does not upload local drafts.
optimize --harness HARNESS --candidate UUID --action review	Read the candidate’s current private revision	Offers a decision to share, retain privately, or dismiss.
optimize --harness HARNESS --candidate UUID --action keep	Retain a selected local candidate	Leaves the draft private without fleet publication.
optimize --harness HARNESS --candidate UUID --action dismiss	Dismiss the selected candidate	Stops further notices for that candidate.
optimize --harness HARNESS --action disable	Turn off native optimization	Does not replace the separate connection or shared rules state.
optimize --harness HARNESS --action enable	Turn on native optimization	Candidate drafting still supplies advisory material.
optimize --harness HARNESS --candidate UUID --action stage	Copy script-backed files to a local staging directory	Does not stage Git changes or publish a resource.
optimize --harness HARNESS --candidate UUID --action reference	Generate a reviewable skill variant	The resulting variant still needs the Team Rules Git review process.
contribute --harness HARNESS --candidate UUID	Display bounded submission content and request confirmation	The bridge cannot automatically submit the candidate.

Native optimization supports claude-code and codex. Choose an existing candidate UUID. A script-backed candidate needs meaningful passing verification before submission.

Select the candidate and a real test program. Candidate verification uses the staged candidate directory.

betterloop verify --harness codex --candidate UUID -- node tests/check.test.mjs

The program runs directly without a shell. Execution has a two-minute timeout. Verification checks the exact file bytes before and after the run.

A passing receipt identifies the candidate digest. Failure remains neutral; it is not attributed as a fleet lesson failure.

Choose an entry already exposed in the matching session, plus a meaningful repository check.

betterloop verify --harness codex --entry ENTRY_ID --session SESSION_ID -- npm test

A later success report can cite the passing receipt for its existing exposure. A completed model turn cannot supply that verified outcome on its own.

Fleet publication still requires human review and signing. Skill and script variants follow Team Rules review. Executable scripts do not become fleet packs.

07 / CLI reference

Support labels and retained local state

Support labels and retained local state
Reported support	What you can conclude
enforced	An enrolled compatible runtime evaluates the supported action through its native gate.
conditional	The check depends on the stated execution route and required conditions.
advisory	Instructions are delivered without guaranteed runtime enforcement.
unsupported	The adapter lacks support for the relevant control, event, catalog version, or runtime version.

Assess support per action and lifecycle event. A required unsupported control prevents a fully governed result. Review the exact required conditions.

Native hook errors or timeouts can permit execution. Client evidence is not independent machine attestation. Native managed settings retain their authority.

Support labels and retained local state
Local location	Stored or coordinated state	Recovery consideration
~/.betterloop/setup.lock	Serializes installation changes	Confirm process exit before removing an abandoned empty lock directory.
~/.betterloop/device/library.lock	Serializes catalog selection changes	Clear an abandoned empty directory only after its library process has exited.
~/.betterloop/runtimes/	User-owned stable plugin handlers	Runtime handlers remain independent of the temporary npx package cache.
~/.betterloop/removed/	Private archives for recovery	Retained revoked credentials cannot restore authorization.
.betterloop/optimizations/UUID/revision-N/	Explicit staging copies for candidate verification	Files are not added to Git through this staging operation.

Use status and doctor for supported inspection. Preserve modified or unowned files during recovery. Select a targeted operation for an isolated resource problem.

The diagnostic guide maps symptoms to repairs. The task recipes combine these command forms into complete procedures.