Skip to content

Repository navigation

cli.md

Latest commit

 

History

History
166 lines (124 loc) · 9.59 KB

cli.md

File metadata and controls

166 lines (124 loc) · 9.59 KB
Raw

CLI

The CLI validates trusted configuration and manages bounded local runs. Install the loopwright command on your laptop first via Installation, then use it to prepare, inspect, resume, or reconcile work and audit capability closure.

Contents

Step 1: Generate drafts

loopwright init --directory ./loopwright-config

The command creates controller.draft.yaml, registry.draft.yaml, and README.draft.md for Managed Controller workflows (for a complete populated setup, follow Managed Controller). Note that loopwright init does not generate .loopwright/taskpack.yaml; to bootstrap or migrate a repository Taskpack interactively, use the llms.txt bootstrap prompt.

apiVersion: loopwright.dev/v1alpha1
kind: TrustedRegistry
metadata:
  name: operator-draft
spec:
  version: 1
  resourceVersion: context-draft
  handlers: []
  roleProfiles: []
  runtimeProfiles: []
  resources: []
  credentialBindings: []
  environmentBindings: []
  • Draft: The excerpt shows the generated registry; controller.draft.yaml contains REVIEW_REQUIRED placeholders that must be replaced before execution.
  • Authority: Keep approved registry bytes and run state outside the checkout.
  • Context: proven_bound is the strict default; estimated guards require explicit immutable opt-in.
File Purpose
controller.draft.yaml Task, registry name + digest, profile references, and controls
registry.draft.yaml Trusted handlers, profiles, resources, and bindings
README.draft.md Draft readiness and review instructions

Step 2: Approve bindings

Review the task scope, exact installed profiles, handlers, credentials, and registry bytes. Replace every placeholder and calculate the SHA-256 of the final approved registry. The generated digest matches only the initial draft bytes.

Step 3: Check configuration

loopwright check --config CONFIG --registry REGISTRY --registry-sha256 DIGEST --json
loopwright run --dry-run --config CONFIG --registry REGISTRY --registry-sha256 DIGEST --json

Both commands validate and compile statically. Neither proves execution readiness, provider availability, or host qualification.

Step 4: Run work

loopwright run --config CONFIG --registry REGISTRY --registry-sha256 DIGEST --repo REPO --run-root TRUSTED_ROOT --run-id demo
loopwright resume --config CONFIG --registry REGISTRY --registry-sha256 DIGEST --repo REPO --run-root TRUSTED_ROOT --run-id demo

Use resume for an existing run with the same trusted identity and bindings. Do not replay an uncertain external effect.

run, resume, and reconcile accept --output-format <csv> with json, github-step-summary, markdown, and text. Use --step-summary-file <path> to select the summary file. With --json, stdout stays pure NDJSON. The CLI does not emit selected Markdown or text reports in this mode. Use --step-summary-file to write a separate Markdown summary. Without --json, selected reports go to stdout.

Step 5: Inspect recovery

Recovery, receipt reconciliation, and closure audit

loopwright status --run-root TRUSTED_ROOT --run-id demo --json
loopwright inspect --run-root TRUSTED_ROOT --run-id demo --output INSPECTION_DIR --json
loopwright reconcile --config CONFIG --registry REGISTRY --registry-sha256 DIGEST --repo REPO --run-root TRUSTED_ROOT --run-id demo --receipt RECEIPT --json

Inspect state and evidence before recovery. Reconcile an unknown external outcome with its matching authenticated receipt; absent evidence stays unknown.

Step 6: Audit closure

loopwright closure --verify-failures --json

Closure exits 0 for a valid report, 3 for falsification or unsupported capability, 4 for failure-matrix failure, and 8 for integrity failure. JSON output uses versioned envelopes with kind, sequence, run identity, and data.

Disposition Evidence scope Meaning
closed_local Recorded local evidence level Local criterion and failure matrix passed
blocked_external Unprovisioned external dependency Live service, host, or hardware remains external
deferred_owned Deferred owned capability Recorded prerequisite remains unimplemented or deferred

Delegated stepping

Use step to hand each delegated role to a host agent (see Coding Agents for the end-to-end coroutine workflow and overlay application). Start with either trusted configuration or a taskpack:

loopwright step next --config CONFIG --registry REGISTRY --registry-sha256 DIGEST --repo REPO --run-root TRUSTED_ROOT --run-id demo --json
loopwright step next --taskpack TASKPACK --repo REPO --run-root TRUSTED_ROOT --run-id demo --json
loopwright step submit --run-root TRUSTED_ROOT --run-id demo --lease TOKEN --status completed --json
loopwright step cancel --run-root TRUSTED_ROOT --run-id demo --json

Use --action next, --action submit, or --action cancel instead of a positional action. step next accepts --mode candidate|no-change. A parked run rejects another pull unless --reissue-lease replaces a lost lease. Submit each single-use --lease token once. --submission-file supplies an artifact; --status accepts completed, no_change, failed, or blocked. Use --reason for a failure or block.

JSON output is NDJSON. An envelope with kind: 'step' contains data.status: 'awaiting_role', selection, prompt, allowed tools, scope, workspace paths, and lease token. Follow those bounds before submitting. Cancellation exits 130; SIGINT and SIGTERM exit 130 and 143, subject to uncertainty precedence.

check, run, resume, and step next accept repeatable --role-model ROLE=PROVIDER/MODEL[:THINKING]. Supply at most eight entries. The CLI limits the argument vector to 64 entries. See Controller and Registry for precedence and persistence.

Command reference

Subcommand Required flags Optional flags Purpose
init --directory --force, --json Emit controller.draft.yaml and registry.draft.yaml
check --config, --registry, --registry-sha256 --output, --json Compile and verify configuration and registry digest statically
run --config, --registry, --registry-sha256, --repo, --run-root, --run-id --json, --output-format, --step-summary-file Execute a bounded controller run
run --dry-run --dry-run, --config, --registry, --registry-sha256 --output, --json Compile plan statically (--repo, --run-root, --run-id disallowed)
resume --config, --registry, --registry-sha256, --repo, --run-root, --run-id --json, --output-format, --step-summary-file Resume an existing run under identical trusted bindings
step --run-root, --run-id, action --action, --json Pull, submit, or cancel delegated work
status --run-root, --run-id --json Read current run stage, lease state, and checkpoint summary
inspect --run-root, --run-id --output, --json Export redacted run receipts, checkpoints, and diagnostics
reconcile --config, --registry, --registry-sha256, --repo, --run-root, --run-id, --receipt --output, --json, --output-format, --step-summary-file Settle an unknown external outcome with an authenticated receipt
closure None --repo, --output, --verify-failures, --json Audit the 23-capability closure matrix and 14-case failure suite
app-serve --config --repo, --json Start the opt-in GitHub App HTTP webhook and token listener 
loopwright app-serve --config github-app.yaml --repo . --json

Set spec.listen.enabled: true first. The command exits 2 for disabled or invalid configuration, 130 on SIGINT, and 143 on SIGTERM. See GitHub App for configuration and host requirements.

Exit codes

Code Meaning
0 Completed, no change, or successful static command
2 Usage or configuration rejected
3 Unsupported capability or blocked work
4 Execution or acceptance failed
5 Allowance exhausted
6 Deadline expired
7 Reconciliation or ownership needed
8 Authoritative result unavailable or incident
130 Step cancellation or accounted SIGINT, subject to uncertainty precedence
143 Accounted SIGTERM, subject to uncertainty precedence

See also — Coding Agents (drive zero-secret loopwright step loops from OAuth coding agents) · Installation (install @gpustack/loopwright and copy bootstrap prompts) · Controller and Registry (approve trusted execution bindings)

Next → Managed Controller — populate registry.yaml and controller.yaml end to end.