Submit, inspect, and govern Runs from your terminal.

Install goclaw

The current public installation path requires Go 1.26 or newer. The command installs goclaw into GOBIN, or GOPATH/bin when GOBIN is unset.

go install github.com/menglingwei/goclawai/cmd/goclaw@latest
goclaw version

Until the first signed binary Release is available, production automation should replace @latest with an explicitly reviewed version or commit.

Connect your workspace

The CLI uses the production API, a workspace ID, and a short-lived access token. Inject the token from a secret manager; never use a provider key or place the token in command arguments or repository files.

export GOCLAW_ENDPOINT=https://goclawai.com/api/v1
export GOCLAW_WORKSPACE=ws_your_workspace
export GOCLAW_TOKEN=your_short_lived_access_token

goclaw doctor
goclaw workspace current

The current CLI does not provide interactive login. Obtain GOCLAW_TOKEN from a registered OAuth client or your workspace administrator.

Submit a Run from JSON

The request file must contain workload, provider, and region; unknown fields are rejected. Keep one idempotency key for one logical operation so timeout retries remain safe.

{
  "workload": {"image": "alpine"},
  "provider": "auto",
  "region": "auto"
}

goclaw run submit --file run.json \
  --idempotency-key onboarding-run-001 \
  --output json

Inspect, cancel, and check usage

run get returns status, provider, and the derived Condition. cancel only requests cancellation; keep polling until cancellationStatus and cleanupStatus reach terminal values.

goclaw run get run_123
goclaw run cancel run_123 --idempotency-key cancel-run-123
goclaw usage summary --output json

Decide high-risk approvals explicitly

Read the Approval risk, bounds, expiry, and version before deciding it. expected-version prevents overwriting a concurrent decision.

goclaw approval get appr_123 --output json

goclaw approval approve appr_123 \
  --expected-version 1 \
  --reason reviewed_change

# Or reject it
goclaw approval deny appr_123 --expected-version 1 --reason unsafe_scope

Use stable output and exit codes in automation

Use --output json in automation. stdout carries results; non-zero exit codes distinguish usage, authentication, authorization, not found, conflict, timeout, and provider unavailability.

• Generate completion with goclaw completion zsh|bash|fish|powershell.
• Inspect MCP discovery with goclaw mcp metadata.
• Debug output must still exclude tokens, provider keys, and Run content.

0 success       1 generic failure
2 usage         3 authentication
4 authorization 5 not found
6 conflict      7 timeout
8 provider unavailable