awcctl command reference¶

awcctl is the reference CLI for AWC (spec §5.1, §8.9). It creates snapshots, forks and mounts workspaces, checkpoints, diffs, and exports. Every mutation honors an idempotency key (spec §13.1).

Synopsis¶

awcctl [GLOBAL FLAGS] <command> [FLAGS] [POSITIONAL]

Global flags are declared global, so you may place them before or after the subcommand. None of the global flags has a short form.

Transports¶

awcctl speaks two transports (spec §8.9).

Transport	Endpoint	Used for
Host daemon (`awcd`)	Unix socket, gRPC `awc.host.v1`	`status`, `workspace mount`, `workspace checkpoint`, `workspace unmount`
Control plane (`awc-control`)	HTTPS, JSON `awc-api::v1`	`snapshot *`, `workspace fork`, `workspace status`, mount ticket in `workspace mount`

workspace mount uses both transports. It issues a signed ticket over the control plane, then redeems the ticket at the host daemon (spec §13.8, §13.9).

Global flags¶

Flag	Env var	Type	Default	Effect
`--output`	`AWC_OUTPUT`	enum	`text`	Output format. Values: `text`, `json`.
`--quiet`	`AWC_QUIET`	bool	`false`	Suppress progress output on stderr. Results still print.
`--host-socket`	`AWC_HOST_SOCKET`	path	`/run/awcd/awcd.sock`	Path to the local `awcd` Unix socket.
`--control-endpoint`	`AWC_CONTROL_ENDPOINT`	URL	none	Base URL of the control plane, for example `https://control.example`.
`--token`	`AWC_TOKEN`	string	none	Bearer token for control-plane auth. The env value is hidden from help.
`--tenant`	`AWC_TENANT`	string	none	Tenant id. Required for snapshot upload.
`--project`	`AWC_PROJECT`	string	none	Project id. Required for most control-plane commands.
`--idempotency-key`	`AWC_IDEMPOTENCY_KEY`	string	none	Idempotency key for the next mutating request (spec §13.1).

--version and -V print the CLI version. --help and -h print help. Both are available on every subcommand.

Under --output json, results are printed as JSON on stdout and progress on stderr. Errors are printed as a JSON document on stdout plus a human-readable line on stderr. The JSON error document carries the control-plane error code, the message, the exit code, and the request id.

Retries

Control-plane requests retry transient failures with bounded exponential backoff and full jitter (spec §17.5). Defaults: 3 attempts, 200 ms base, 5 s cap. Retryable HTTP statuses are 408, 425, 429, and 5xx except 501 and 505. Mutations are safe to retry because of the idempotency key.

Top-level commands¶

Command	Summary
`status`	Show host-daemon health and mount state.
`snapshot`	Create, inspect, list, diff, and export snapshots.
`workspace`	Fork, inspect, mount, checkpoint, and unmount workspaces.

awcctl status¶

Shows host lifecycle and base-mount state from the host daemon. The GetHostStatus RPC has no dedicated spec section (do not confuse it with §13.9, which is MountWorkspace). Uses the host transport only.

awcctl status

Text-mode fields: host, state, version, basefs, basefs path, mounts, started, and detail when non-empty.

awcctl snapshot¶

snapshot create¶

Creates an immutable snapshot from a prepared directory through a resumable upload (spec §5.2, §13.3 to §13.5). Uses the control transport and an object store.

awcctl snapshot create --from-dir <DIR> [--name <NAME>] [FLAGS]

Flag	Type	Required	Default	Effect
`--from-dir`	path	yes		Source directory to import.
`--name`	string	no	none	Human-friendly snapshot name.
`--source-type`	enum	no	`directory`	Source kind. Values: `directory`, `git`, `tar`.
`--normalization`	enum	no	`source-normalized`	Metadata normalization policy. Values: `source-normalized`, `environment-preserving`.
`--object-store-endpoint`	URL	no	none	Object store for resumable upload. The scheme selects the backend, for example `s3://my-bucket` or `memory://`.
`--label`	`KEY=VALUE`	no	none	Label. Repeat the flag to add more than one.
`--idempotency-key`	string	no	none	Overrides the global key for this upload.

The object store is selected from --object-store-endpoint, else the AWC_CAS_URL env var. The value scheme selects the backend: memory:// for the in-memory store, s3:// for S3-compatible storage. The s3:// scheme requires the s3 build feature. S3 credentials come from the AWC_S3_* env vars.

Text-mode fields: snapshot_id, state, manifest, logical_bytes, file_count.

snapshot inspect¶

Shows one snapshot's metadata. Uses the control transport. (The spec gives no dedicated read section; §13.5 is the import-completion RPC.)

awcctl snapshot inspect <ID>

Argument	Type	Required	Effect
`ID`	snapshot id	yes	Snapshot id to inspect.

Text-mode fields: id, state, manifest, root tree, files, bytes, source, normalized, and parent when set.

snapshot list¶

Lists snapshots, with optional filters. Uses the control transport. (The spec gives no dedicated list section; §13.5 is the import-completion RPC.)

awcctl snapshot list [--project <ID>] [--state <STATE>] [--parent <ID>]

Flag	Type	Required	Default	Effect
`--project`	project id	no	none	Filter by project.
`--state`	string	no	none	Filter by snapshot state.
`--parent`	snapshot id	no	none	Filter by parent snapshot.

snapshot diff¶

Compares two snapshots (spec §13.14). Uses the control transport.

awcctl snapshot diff <LEFT> <RIGHT> [--format <FORMAT>]

Argument	Flag	Type	Required	Default	Effect
`LEFT`		snapshot id	yes		Left snapshot id.
`RIGHT`		snapshot id	yes		Right snapshot id.
	`--format`	enum	no	`json`	Output format. Values: `json`, `patch-bundle`, `tar`.

For json, a structured result prints on stdout. For patch-bundle and tar, the raw artifact streams to stdout. For large diffs, the control plane may return a job id instead of an inline result.

snapshot export¶

Exports the changes of one snapshot against another (spec §13.14). Uses the control transport.

awcctl snapshot export <SNAPSHOT> --against <BASE> [--format <FORMAT>] [--out <PATH>]

Argument	Flag	Type	Required	Default	Effect
`SNAPSHOT`		snapshot id	yes		Snapshot whose changes are exported.
	`--against`	snapshot id	yes		Base snapshot to compare against.
	`--format`	enum	no	`patch-bundle`	Output format. Values: `json`, `patch-bundle`, `tar`.
	`--out`	path	no	`-`	Output file. Use `-` for stdout.

Spec and code disagree

Spec §5.1 names the output flag --output. The code implements --out. This page documents the code, which is what ships.

awcctl workspace¶

workspace fork¶

Forks private workspaces (spec §5.3, §13.6, §13.7). Uses the control transport. There are two modes:

--snapshot forks one workspace from a snapshot (POST /v1/workspaces).
--workspace batch-forks from an existing workspace (POST /v1/workspaces/{id}:fork).

You must pass exactly one of --snapshot or --workspace.

awcctl workspace fork --snapshot <ID> --ttl <DURATION> [FLAGS]
awcctl workspace fork --workspace <ID> --ttl <DURATION> [--from <SRC>] [--count <N>] [FLAGS]

Flag	Type	Required	Default	Effect
`--snapshot`	snapshot id	one of	none	Fork one workspace from this snapshot.
`--workspace`	workspace id	one of	none	Batch-fork from this existing workspace.
`--from`	enum or id	no	`head`	With `--workspace`. Values: `base`, `head`, or a snapshot id.
`--count`	integer	no	`1`	Number of workspaces. Only with `--workspace`.
`--ttl`	duration	yes		Workspace lifetime, for example `2h`.
`--name`	string	no	none	Name for one fork, or name prefix for a batch.
`--label`	`KEY=VALUE`	no	none	Label. Repeat the flag to add more than one.

With --snapshot, --count must be 1. The --snapshot path requires --project.

A --ttl value is a number with an optional unit. Units: s, sec, secs, seconds; m, min, mins, minutes; h, hr, hrs, hours; d, day, days. A bare number is seconds.

workspace status¶

Shows one workspace's metadata. Uses the control transport. (The spec gives no dedicated read section; §13.6 is the create-workspace RPC.)

awcctl workspace status <ID>

Argument	Type	Required	Effect
`ID`	workspace id	yes	Workspace id to inspect.

Text-mode fields: id, state, base, head, version, lease gen, expires.

workspace mount¶

Mounts a workspace onto an authorized target (spec §5.4, §13.8, §13.9). Uses both transports.

awcctl workspace mount <WORKSPACE> --target <PATH> [--read-only]

Argument	Flag	Type	Required	Default	Effect
`WORKSPACE`		workspace id	yes		Workspace id to mount.
	`--target`	path	yes		Target mount path. Must fall under the host allow-list.
	`--read-only`	bool	no	`false`	Mount read-only. Default is read-write.

Text-mode fields: session, target, merged, root, lease gen.

Spec and code disagree

Spec §5.1 shows --mode read-write and --mode read-only. The code implements a single --read-only boolean flag. This page documents the code.

workspace checkpoint¶

Persists an immutable checkpoint of a mounted workspace (spec §5.5, §13.11). Uses the host transport. The positional argument is the mount session id that workspace mount returned.

awcctl workspace checkpoint <MOUNT_SESSION_ID> [--message <MSG>] [--mode <MODE>] [FLAGS]

Argument	Flag	Type	Required	Default	Effect
`MOUNT_SESSION_ID`		string	yes		Mount session id from `mount`.
	`--message`	string	no	none	Checkpoint message.
	`--mode`	enum	no	`quiesced`	Checkpoint mode. Values: `quiesced`, `cooperative`.
	`--label`	`KEY=VALUE`	no	none	Label. Repeat the flag to add more than one.
	`--idempotency-key`	string	no	none	Overrides the global key for this checkpoint.

Progress streams to stderr as checkpoint <stage>: <done>/<total> bytes.

Text-mode fields: snapshot, digest, version, logical bytes, uploaded bytes, changed paths.

Spec and code disagree

Spec §5.1 passes a workspace id to checkpoint. The code takes the mount session id. This page documents the code.

workspace unmount¶

Unmounts a session with a chosen disposition for local changes (spec §11.11, §13.13). Uses the host transport.

awcctl workspace unmount <MOUNT_SESSION_ID> [--disposition <DISP>] [--idempotency-key <KEY>]

Argument	Flag	Type	Required	Default	Effect
`MOUNT_SESSION_ID`		string	yes		Mount session id.
	`--disposition`	enum	no	`discard-local`	Disposition for local changes. Values: `discard-local`, `checkpoint`, `preserve-local`.
	`--idempotency-key`	string	no	none	Overrides the global key for this unmount.

Argument value enums¶

Enum	Values
`--output`	`text`, `json`
`--source-type`	`directory`, `git`, `tar`
`--normalization`	`source-normalized`, `environment-preserving`
`--from` (workspace fork)	`base`, `head`, or any snapshot id
`--mode` (checkpoint)	`quiesced`, `cooperative`
`--disposition` (unmount)	`discard-local`, `checkpoint`, `preserve-local`
`--format` (diff, export)	`json`, `patch-bundle`, `tar`

Exit codes¶

Every failure maps to a stable exit code (spec Appendix E). The exit code is the authoritative contract for CI and sandbox integrations.

Code	Meaning	Example cause
`0`	Success	Command completed.
`2`	Invalid command or argument	Unknown subcommand, bad id, missing required flag, clap parse error, `INVALID_ARGUMENT`, `MOUNT_UNSUPPORTED`.
`3`	Authentication or authorization failure	`UNAUTHENTICATED`, `PERMISSION_DENIED`, `HOST_NOT_AUTHORIZED`.
`4`	Resource not found	`NOT_FOUND`.
`5`	Conflict, busy workspace, or stale version	`ALREADY_EXISTS`, `IDEMPOTENCY_CONFLICT`, `SNAPSHOT_NOT_READY`, `WORKSPACE_EXPIRED`, `WORKSPACE_BUSY`, `STALE_LEASE_GENERATION`, `WORKSPACE_VERSION_CONFLICT`, `WRITER_LEASE_HELD`.
`6`	Local host or mount failure	Host socket unreachable, local I/O error, gRPC `UNIMPLEMENTED`.
`7`	Object-store or remote I/O failure	`OBJECT_MISSING`, `OBJECT_STORE_UNAVAILABLE`, transport error, decode error.
`8`	Checkpoint or integrity failure	`OBJECT_CORRUPT`, `CHECKPOINT_PUBLICATION_FAILED`, `QUIESCE_FAILED`, checkpoint stream ended with no result.
`9`	Resource limit exceeded	`RESOURCE_EXHAUSTED`.
`10`	Temporary control-plane unavailability	`CONTROL_PLANE_UNAVAILABLE`, gRPC `UNAVAILABLE`.

For the full list of error codes and their retryability, see error codes. Under --output json, machine consumers SHOULD parse the JSON error document instead of relying on the numeric code alone (spec Appendix E).

Current scope¶

This page reflects the current build of awcctl.

The CLI implements the subcommands and flags listed above. There is no workspace delete, workspace lease, or snapshot delete subcommand in the current build, even where the spec discusses related lifecycle behavior.
Git and tar source import (--source-type git, --source-type tar) are declared by the CLI and accepted by the parser. The launch-critical path is local-directory import (spec §5.2).
The --label flag is a key-value pair. The CLI rejects an empty key or a value without an = sign.
Lease renewal, checkpoint publication, and object-store batch checks are internal control-plane or host-daemon operations. They are not exposed as awcctl subcommands.
The mount --mode flag shown in spec §5.1 is not implemented. Use --read-only.
The export --output flag shown in spec §5.1 is not implemented. Use --out.