constle docs constle docs v0.5.0pre-1.0

CLI reference

One binary, constle. Run it bare for the command overview, or constle version for the version.

On this page

CommandsLink to this section

Command What it does
constle [--no-animation] Show the startup screen and command overview. The flag skips the animated intro.
constle init Create agent.yaml with sensible defaults in the current directory.
constle run [--backend=docker|firecracker] [--accept-isolation=<level>] <agentfile> Run an agent in an isolated sandbox.
constle validate <agentfile> Check an Agentfile without running it. Prints the resolved isolation and warns about every declared control that won't be enforced.
constle ps List running and recent Constle-managed agents.
constle stop <run-id> Stop a running agent by run ID.
constle identity create [--owner=<email>] <name> Create a cryptographic agent identity (did:key, an Ed25519 keypair).
constle identity show <name> Show an agent's DID and key location.
constle webhook-keygen <name> Generate a human-gates approver keypair (did:key) for human_gates.approver_pubkey.
constle audit verify [--agentfile=<path>] [--did=<did:key:…>] [--approver-pubkey=<did:key:…>] <logfile> Verify a signed audit log (signatures and hash chain), and re-verify the human-gate decisions it records.
constle version Print the version.

constle runLink to this section

shell
constle run [--backend=docker|firecracker] [--accept-isolation=<level>] <agentfile.yaml>
  • --backend=<name> forces a backend: docker or firecracker. By default one is auto-detected. Forcing Docker does not relax the isolation contract: an Agentfile that needs kernel is refused on Docker.
  • --accept-isolation=<level> (none, process or network) runs at a weaker isolation level than the Agentfile declares, for this run only. The level must be strictly weaker than the declared minimum; the run prints ISOLATION DOWNGRADE ACCEPTED and records both levels in its run_started audit entry. It cannot waive a capability-floor validation error. See Architecture.
  • There is no --env flag. The agent receives exactly the host variables named under credentials: and nothing else.

constle validateLink to this section

shell
constle validate <agentfile.yaml>

Parses and validates without running anything. It prints the resolved isolation (and whether it was declared or inferred from capabilities), and warns about each control that is declared but won't be enforced: spending caps with nothing to meter, gate entries that can match no tool, max_per_month_usd, and the like.

constle identityLink to this section

shell
constle identity create [--owner=<email>] <agent-name>
constle identity show <agent-name>

create writes an Ed25519 key to ~/.constle/identities/<name>/key.pem (mode 0600) and prints the DID to paste into identity.did. --owner binds a label that must match the Agentfile's identity.owner when both are set. See Identity.

constle webhook-keygenLink to this section

shell
constle webhook-keygen <name>

Creates the approver keypair for human gates under ~/.constle/webhook-keys/<name> (mode 0600) and prints the did:key to paste into human_gates.approver_pubkey. It is not an agent identity: it authenticates the human approving gated calls, and the private key goes to whoever operates the decision endpoint.

constle audit verifyLink to this section

shell
constle audit verify [--agentfile=<path>] [--did=<did:key:…>] [--approver-pubkey=<did:key:…>] <logfile>
Flag Pins
--agentfile=<path> both of the pins below, taken from an Agentfile
--did=<did:key:…> the identity the log must be signed with
--approver-pubkey=<did:key:…> the human_gates.approver_pubkey that the log's recorded gate decisions must verify against

Unpinned, a check only shows that the log is internally consistent. See Audit log and verification.

Environment variablesLink to this section

Variable Effect
CONSTLE_ANIMATION auto (the default), never or always: whether bare constle plays the startup animation.
CONSTLE_REQUIRE_SIGNATURE Read by the installer: 1 refuses any release whose checksums.txt signature can't be verified. See Verifying a release.
The one url_secret_ref names Holds the human-gates webhook URL, so it never sits in the Agentfile (for example HUMAN_GATE_WEBHOOK_URL).
The ones credentials names Passed into the sandbox, by name, and nothing else.

Running bare constle in an interactive terminal plays the startup animation before the command overview. Use constle --no-animation to skip it for one invocation, or set CONSTLE_ANIMATION. The animation is always suppressed for non-interactive output, NO_COLOR, TERM=dumb, or terminals smaller than 80×24; always overrides CI detection only.

Verifying a releaseLink to this section

Checking a downloaded release with cosign and sha256sum, and what the installer checks for you, has its own page: Verifying a release.

Report an issue with this page