awrk CLI

The executable is awrk (wrk remains a legacy alias). The CLI package has not yet crossed the public npm publication gate, so this guide does not claim a public global-install command. In an installed pilot environment, use awrk; while developing this repository, use pnpm awrk from the monorepo root.

Repository setup

1. Run the CLI from the repository that will use shared context.
2. Create .wrk.yml at that repository's root. If the awrk example is present, start with cp .wrk.yml.example .wrk.yml.
3. Fill in the service URL, canonical workspace ID, and GitHub owner/repository; add a canonical project object ID only when the work should be scoped to one project.
4. Run awrk login, complete the browser flow, then run awrk auth status and awrk config.
5. Preview the desired target adapters, write them explicitly, and validate them with awrk integrations doctor.

awrk login
awrk login --scope objects:read --scope objects:write
awrk auth status
awrk config
awrk integrations install --all
awrk integrations install --all --write
awrk integrations doctor

For exact Claude Code, Codex, Cursor, GitHub Copilot, Windsurf, OpenCode, Pi, and OpenClaw procedures, see Install awrk for every agent and IDE.

Configure environment variables or a repository-local .wrk.yml:

schemaVersion: 1
apiUrl: https://wrk.example.com
workspace: wrk_01JEXAMPLEWORKSPACEID
repository: owner/repository
project: obj_01JOPTIONALPROJECTID

This flat v1 file is discovered from the current directory upward. schemaVersion may be omitted only for legacy compatibility. workspace must be the canonical ID returned by awrk workspaces list; slugs are not routing keys. repository is a GitHub owner/name, and project is an optional canonical obj_... ID.

Do not put tokens, client secrets, passwords, or credentials in .wrk.yml; the CLI rejects secret and unknown keys. Keep authentication in environment variables or your local secret manager.

Authenticate

Interactive users authenticate through awrk's OAuth issuer. The CLI discovers the canonical MCP protected resource, dynamically registers a public client, uses Authorization Code with S256 PKCE, listens only on a temporary 127.0.0.1 callback, and stores the resulting resource-bound OAuth credential in a user-local file with owner-only permissions:

awrk login
awrk auth status
awrk logout

Use awrk login --no-open to copy the authorization URL manually into a browser on the same machine; the callback is intentionally loopback-only. A credential issued by the former Cloudflare Access issuer is rejected with instructions to run awrk logout and awrk login. WRK_API_TOKEN always overrides a stored OAuth credential.

An authenticated workspace owner can mint a scoped API key for a headless agent. The raw key is returned once:

awrk auth api-key create --name "CI agent" --capability objects:read --capability objects:write --expires 2026-10-20T00:00:00Z

If a production hostname intentionally retains an overlapping Cloudflare Access policy, a headless API-key client must also supply CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET for an authorized Access service token. The awrk API key controls workspace capabilities; the Access service token only crosses that optional perimeter.

Install the automatic agent loop

Preview the project-local integration bundle for all supported agents, then write it explicitly:

awrk login
awrk integrations install --all
awrk integrations install --all --write
awrk integrations doctor

Supported runtime names are claude, codex, cursor, copilot, windsurf, opencode, pi, and openclaw. Use repeatable --runtime flags to install a subset. The installer derives the authenticated MCP URL from .wrk.yml, generates one canonical loop, and adds thin native skill/rule adapters. It preserves unrelated MCP entries and existing AGENTS.md content, refuses to overwrite unmanaged dedicated files unless --force is explicit, and writes no credentials.

The installed rule requires the agent to call wrk_checkout_context before meaningful work, execute in its native runtime, and call wrk_commit_contribution before its final response. When MCP is unavailable, the same rule uses the awrk context checkout and awrk contribution commit CLI commands as a degraded fallback. Work Lease remains planned and is never represented as active coordination.

OpenClaw receives a compatible bundle under .awrk/bundles/openclaw; install that generated bundle with the command returned by the installer:

openclaw plugins install ./.awrk/bundles/openclaw

integrations doctor validates every generated file against .awrk/integrations.json checksums and reports credential presence as booleans without printing secret values.

awrk search "release blocker" --type task --status blocked
awrk context checkout --intent "Fix the release check"
awrk context checkout --intent "Review auth changes" --runtime codex --repo owner/repository --project obj_123 --limit 20
awrk contribution commit --summary-file result.md --context ctx_123 --learning "The check targets the default branch" --artifact https://github.com/owner/repository/pull/42 --evidence https://github.com/owner/repository/actions/runs/7 --confidence 0.9
awrk integrations install --all --write
awrk integrations doctor
awrk organization-agent create --name "CQ client" --capability knowledge:read --capability knowledge:propose --capability knowledge:feedback
awrk object update obj_123 --file patch.json --version 7
awrk object versions obj_123 --limit 25
awrk object permissions obj_123
awrk object grant obj_123 --principal usr_123 --capability objects:read --capability objects:write
awrk object revoke obj_123 --permission perm_123
awrk members list --limit 25
awrk members update mem_123 --role owner --status active
awrk invites list --limit 25
awrk invites create --email [email protected] --role member --expires-hours 72
awrk invites revoke inv_123 --reason "Seat reassigned"
printf '%s' "$WRK_INVITE_TOKEN" | awrk invites accept --token-stdin
awrk transactions list --limit 25
awrk approvals comments <approval-id>
awrk approvals comment <approval-id> --comment "Checked the release evidence."
awrk approvals reassign <approval-id> --to <approver-user-id>
awrk approvals approve <approval-id>
awrk github repositories --q api --selected false --limit 25
awrk github select
awrk github select <repository-id> --project obj_override
awrk github hydrate --type pull_request --type check_run --limit 10 --idempotency-key hydrate-pilot-1
awrk github evidence-jobs --status failed
awrk github retry-hydration <job-id>
awrk github readiness
awrk github draft-comment --number 42 --body "Ready after approval"
awrk agents create --slug incident-lead --name "Incident lead" --capability objects:read --capability agents:run --protect external:write --model-class fast --fallback deterministic --budget 3
awrk agents update <agent-id> --budget 1.50 --protect objects:update --protect production:write
awrk agents pause <agent-id>
awrk schedules create --agent <agent-id> --name "Weekday brief" --prompt "Prepare release readiness" --cadence weekdays --hour 12
awrk workflow-dispatches list --state failed
awrk workflow-dispatches retry <dispatch-id>
awrk event-deliveries list --status failed --consumer webhooks
awrk event-deliveries retry <delivery-id>
awrk semantic status
awrk semantic jobs --status failed
awrk semantic backfill --type decision --limit 25 --idempotency-key semantic-decisions-1
awrk semantic retry <job-id>
awrk semantic cancel <job-id>
awrk webhooks list
awrk webhooks create --url https://example.com/awrk-events --event object.updated
awrk webhooks revoke <webhook-id>
awrk settings get
awrk settings update --approval objects:update --approval github:write
awrk retention status
awrk retention run --confirm true --idempotency-key retention-2026-07-19
awrk usage
awrk mcp url

Authentication uses either the credential saved by awrk login or WRK_API_TOKEN. When an Access policy overlaps the awrk hostname, non-interactive API-key calls must also set CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET for a service token allowed by that policy. Interactive OAuth-capable MCP clients connect to the URL returned by awrk mcp url and follow the awrk issuer's RFC 9728/RFC 8414 challenge. --limit and --cursor traverse paginated collections. --idempotency-key protects retried writes.

Invite acceptance is intentionally human-only and is not authorized by a workspace-bound MCP OAuth credential. The primary flow is the browser invitation URL (/app?invite=...), which signs the invited person in with Google or GitHub and verifies the invitation email. The CLI command remains available locally and, during the rollback window only, can use CF_ACCESS_TOKEN; it never substitutes WRK_API_TOKEN, a workspace OAuth credential, or Access service-token credentials for the invited human identity.

For github select, exclude, hydrate, draft-comment, draft-merge, and draft-release, an explicit repository ID wins. When it is omitted, the CLI reads .wrk.yml, scans every page of the synchronized repository catalog, and requires exactly one case-insensitive owner/name match. Merely reading or printing configuration never selects, hydrates, or mutates a repository. github select --project overrides the configured project; otherwise select applies the configured project mapping. Release readiness remains workspace-wide and does not narrow itself to the mapped repository.

Approval comments and reassignment are available only while an approval is pending and unexpired. The --to value is a user ID for an active workspace approver or owner.

awrk github readiness prints the same typed report used by the browser and SDK: required-work counts, blockers, caller-visible pending approvals, and versioned source provenance. Restricted objects and approvals are not included unless the active workspace credential has canonical access.

awrk context checkout requires --intent, defaults --runtime to codex, and uses repository and project from .wrk.yml unless --repo or --project overrides them. --limit bounds the ranked packet from 1 to 50. Checkout is read-only and requires objects:read.

awrk contribution commit reads its required summary from --summary-file, defaults runtime to codex and outcome to completed, and accepts repeatable --learning, --followup, --artifact, and --evidence flags. Artifact and evidence flags are URLs; the CLI sends each as a { "type": "url", "url": "..." } reference. Optional --confidence is a number from 0 to 1. Commit requires objects:write; the legacy string --learning input is converted into a pending CQ proposal. It is not returned to another agent until human review.

organization-agent create returns an organization-scoped credential once. Put that value in CQ_API_KEY and point CQ_ADDR at the awrk host. Rotate or revoke it with organization-agent rotate|revoke <credential-id>; never place the raw credential in .wrk.yml.

Evidence hydration is owner-only, single-repository, read-only against GitHub, and bounded to 100 records per requested type. The repository must first be selected explicitly. It imports recent pull requests, issues, default-branch checks, and releases through the durable queue; it does not select repositories or create external write intents.

github draft-comment, github draft-merge, and github draft-release only create approval-gated intents; they never write directly to GitHub. Merge methods are limited to merge, squash, and rebase, and --sha <40-character-head-sha> can bind a merge to the reviewed PR head. Releases are drafts unless --publish true is explicit; --target and --generate-notes true map to GitHub release options.

settings update replaces the workspace approval-policy list and requires at least one repeatable --approval flag, preventing an accidental empty policy from a mistyped command. Supported names are *, objects:write, objects:create, objects:update, objects:link, objects:archive, objects:delete, objects:comment, external:write, github:write, and production:write. Use the browser owner controls when intentionally clearing all configurable matches; external writes and archives still retain their mandatory safety floor.

retention status is a read-only preview. retention run refuses to send the request without the literal --confirm true and the server requires an authenticated human workspace owner; workspace API tokens cannot start cleanup. Scheduled enforcement uses the workspace retention policy automatically.

Workflow dispatch, event-delivery, and webhook commands require an owner credential. Retry commands are idempotent: an already pending, processing, processed, or successfully queued record is returned without duplicating work.

Semantic status and job controls are owner-only. Backfill is stale-only unless --force true is supplied, runs through the existing Queue in resumable chunks, and incurs Workers AI embedding plus Vectorize usage. Start with a small --limit and inspect semantic jobs before widening scope.