CLI reference

gin is one binary. Most commands are thin adapters over the gin.v1 API: each builds one request from its arguments, calls the library or daemon, and prints the response as one line of compact JSON. The CLI adds no semantics of its own: preconditions, paging, refusals and replay are the engine's.

Run gin help for the full usage text of every command.

Session options

Session options come before the command.

Embedded (local) session

Option	Environment	Meaning
--host DIR	GIN_HOST	the worker host directory (object store and journals)
--repository ID	GIN_REPOSITORY	repository identity
--workspace ID	GIN_WORKSPACE	workspace identity
--data DIR	GIN_DATA	a gin serve --data directory no daemon holds: reaches the shared plane and evidence
--principal NAME	GIN_PRINCIPAL	the identity to act as with --data

With --data, contexts report pending publications, conflicts and evidence, origins attribute consumed checkpoints, and plans can be made.

Remote session

Option	Environment	Meaning
--endpoint URL	GIN_ENDPOINT	daemon address; use https:// beyond loopback
--token-file FILE	GIN_TOKEN_FILE	bearer token for a configured identity
--ca-file PEM (alias --tls-ca-file)	GIN_CA_FILE	add a private CA to the bundled Mozilla roots
--tls-server-name NAME	GIN_TLS_SERVER_NAME	verified certificate and SNI name; defaults to the URL host
--allow-plaintext-remote	none	explicit exception for plain HTTP beyond loopback
--insecure-skip-tls-verify	none	debugging only: skips server verification
--timeout SECONDS	none	whole-call deadline; off by default

Remote sessions refuse --host, --data and --principal, including their environment variables. Flags override environment variables.

Common command options

Option	Meaning
--request-id ID	the request's identity; a retried mutation must reuse it
--cursor HEX, --limit N	paging: pass a page's next_cursor back as --cursor

Without --request-id, a random ID is used.

Source commands

context

Workspace epoch, generation, incarnation, parents, changes, sections and safe operations.

gin context

read

Entry and, with --content, bytes of a path in the private tree or in a readable snapshot. With no path, reads the root. Content identities are listed first in stable_ids.

gin read src/lib.rs --content
gin read src --snapshot CHECKPOINT

diff

Changed leaves between two snapshots (default: the private tree), optionally under a prefix.

gin diff --from CHECKPOINT --prefix src

origin

Source origin and history of a path: private, authored, inherited, moved, resolved, rewritten, merged and so on.

gin origin src/lib.rs --limit 64

explain

Explain a workspace, checkpoint or snapshot.

gin explain CHECKPOINT

details

Page a larger explanation by its detail identity.

gin details DETAIL_ID --limit 64

save

Conditionally save private edits. The version flags come first, then one or more edits, each starting with --path.

gin save --incarnation ID --generation N --epoch ID EDIT...
  EDIT = --path PATH --expect absent|CONTENT_ID [--executable] (--text TEXT | --file FILE | --delete)

gin save --incarnation I --generation 3 --epoch E --request-id s-1 \
  --path src/lib.rs --expect CONTENT_ID --text 'pub fn f() {}' \
  --path old.rs --expect OLD_ID --delete

Remote saves also need --lease-incarnation STORE --lease-epoch N (the write fence). --executable does not apply to --delete.

plan

Validation plan of a snapshot: each check reusable, uncertain or required. Needs --data. --evaluation takes a hex-encoded gin.v1.EvaluationKey.

gin --data DATA --principal NAME plan --snapshot CHECKPOINT --evaluation HEX

annotate

Append a comment to an exact checkpoint, optionally anchored to a path, content identity and line range, a change, or accepted evidence. Replies (--reply-to) and corrections (--corrects) are new records.

gin annotate CHECKPOINT --text 'Observed failure' --request-id comment-1 \
  --path src/test.rs --content-id CONTENT --first-line 4 --last-line 7

Text is at most 16 KiB and is always untrusted data.

annotations

List an exact checkpoint's annotations in sequence order. Visibility is not inherited from ancestors.

gin annotations CHECKPOINT --limit 64

capabilities

The server's actual operations and your grants.

gin capabilities

call

Send a complete gin.v1.Request in protobuf JSON. This reaches every operation, including lifecycle ones such as fork, publish, preview and advance. Bytes are base64 in the input; nothing (request ID, attempt ID, expectations, fence) is generated or rewritten for you.

gin call --json "$REQUEST"

Other commands

gin (no arguments)

Print the version.

serve

Run the daemon. See Running the daemon.

gin serve --listen 127.0.0.1:7400 --data /var/lib/gin --auth /etc/gin/auth.conf

mcp

Serve one workspace as an MCP server on stdio. Takes the session options. See MCP reference.

gin mcp --host DIR --repository ID --workspace ID

view

Materialise and manage machine checkouts of exact snapshots through the versioned gin.view/1 JSON lifecycle (used by build systems such as Toki).

gin view capabilities --registry /abs/views --json
gin view --endpoint URL --token-file FILE --repository ID --workspace ID \
  materialise VIEW_ID --registry /abs/views --snapshot CHECKPOINT
gin view ACTION VIEW_ID --registry /abs/views --request request.json --json

For view, session options go after the word view; the registry must be an absolute directory. Actions include resolve, materialise, lookup, inspect, verify, read, admit, finish, release, abort, capture and retire. Each reply is one JSON envelope recording what was requested, applied and refused. Probe capabilities before relying on a feature.

ci upload

Upload a CI job's test results as evidence. See Evidence.

gin ci upload --endpoint URL --repository ID --junit FILE --metadata FILE --artifact NAME

retention

Report or reclaim unreachable storage in a stopped data directory, or retire a worker journal.

gin retention report --data DIR
gin retention collect --data DIR
gin retention retire --data DIR --repository ID --workspace ID [--discard-unpublished yes]

report plans without deleting anything. Nothing is removed because it is old or idle; only objects no root reaches are reclaimed.

verify and repair

Certify a stopped store's objects and references, or recover journals and rebuild the pack index.

gin verify --data DIR [--worker REPOSITORY=DIR ...]
gin verify --git-store DIR
gin repair --data DIR

Stop writers first. Verification performs normal recovery; keep a separate copy if you need untouched crash evidence.

git-http

Call the Git import, export and history routes with the same TLS policy as RPC.

gin git-http --endpoint URL --token-file FILE request [--method GET|POST] [--body-file FILE] [--content-type TYPE]

admin legacy

Offline administration of access rules carried over from older stores. Run with the daemon stopped.

gin admin legacy --data DIR list

Output

Source commands print the response envelope as one line of JSON:

• protobuf field names, unset fields omitted, enum values by name;
• paths, names, link targets and file content are text when they are exact UTF-8, and {"hex": "..."} otherwise;
• opaque bytes (cursors, digests, encoded records) are always {"hex": "..."}.

A refused request prints an error response that includes the current state, so you can re-read and retry.

Exit status

Status	Meaning
0	the engine returned a result
1	the engine returned an error response
2	the command line or session never reached the engine (usage error, bad options, session failed to open)

serve, retention and ci upload also exit 2 on usage errors and 1 on runtime failures.