Documentation
OpenAPIAgent index

CLI and local agents

The Dharma CLI creates an outbound, device-authenticated connection between approved local repositories and the organization control plane. It does not expose an inbound shell and does not upload an unrestricted filesystem.

Requirements

  • Node.js 22 or newer;
  • Git repository access on the local machine;
  • a browser session for the same Dharma organization;
  • a supported local provider installed separately.

Install the pinned production version shown by the portal:

npm install --global @dharma-ai-labs/agent-fabric@0.2.34
hash -r 2>/dev/null || true
dharma --help

dharma --version must print 0.2.34. If an older global npm prefix shadows the release, use npm exec --yes --package=@dharma-ai-labs/agent-fabric@0.2.34 -- dharma until PATH is repaired.

Enroll the device

Copy the exact command from Portal -> Agent Fabric -> Instructions:

dharma login \
  --portal-url https://www.dharma-ai.io \
  --organization-id <organization-id>

The CLI opens a browser approval. Approval creates an Ed25519 device identity; it does not write a reusable organization token into the repository or prompt history.

Connect repositories

Discovery is limited to the root you name. Review the result before connecting anything.

dharma repositories discover --root "$HOME/work"
dharma repositories connect \
  --repo "$PWD" \
  --organization-id <organization-id> \
  --policy-revision <policy-revision>
dharma repositories status --repo "$PWD"

Each selected source repository becomes one logical organization agent. Connecting the same normalized Git remote from another machine or provider reuses that logical agent and adds an endpoint. Absolute local paths are not repository identity.

The organization receives one private Dharma control repository. Its permanent agent branches hold manifests, evaluation definitions, signed skills, releases, and receipts; they do not mirror the customer source repository.

Install and verify provider skills

The onboarding flow installs the repository bootstrap and the provider-native integration for detected supported providers. Restart the provider after first installation.

dharma providers list
dharma skills sync --workspace .
dharma skills verify --provider codex --workspace .
dharma skills verify --provider claude --workspace .
dharma skills status --workspace .

Provider capabilities are independent. Discovery does not prove capture, task execution, skill activation, or rollback. The authenticated Instructions page reports the receipts for each connected endpoint.

Capture and synchronize evidence

Complete raw trajectories remain in the encrypted local vault unless the organization has approved a bounded content policy. Preview the exact outgoing capsule before sending it.

dharma evidence preview --workspace .
dharma evidence capture --workspace .
dharma evidence sync --workspace .
dharma relay start --policy .dharma/approved-policy.json

Metadata-only evidence can identify runtime failures, incomplete work, tool-discipline anomalies, and candidates for deeper review. Semantic claims require approved content evidence or a separately governed local semantic evaluator.

Use the organization control agent

The CLI can talk to the same managed control agent shown in the portal without placing a durable token in the prompt.

dharma assistant chat --message "Summarize open failure families" --confirm
dharma assistant history
dharma assistant status --session-id <session-id>

Reads may complete automatically. Paid or mutating operations become bounded proposals. dharma assistant approve and dharma assistant reject open the authenticated portal at the exact proposal; the URL itself cannot approve an action.

Organization operations

Role-scoped commands include organization status, agents, experiments, failures, remediations, tasks, handoffs, skills, usage, rollout, and rollback. Use --json for automation. Every mutation requires the matching scope, an idempotency key where applicable, and explicit confirmation.

Remove access

Revoke the device in Portal -> Agent Fabric -> Devices, stop the relay, and remove the local workspace binding. Revocation prevents new signed work; repository and historical audit records remain subject to the organization's retention policy.