Gitslice docs

CLI Reference

A compact lookup for the commands used in normal Gitslice work. Use Start Here for the walkthrough.

Install the gs CLI

The CLI is a single Go binary named gs. Prebuilt binaries need nothing else; building it yourself requires Go 1.24 or newer.

Option A — prebuilt binary (quickest)

curl -fsSL https://gitslice.io/install.sh | sh

Downloads the latest release for Linux or macOS (amd64 or arm64), verifies its checksum, and installs it to ~/.local/bin. Windows and other builds are on the releases page.

To read and check the script before running it: each release carries its own copy, listed in that release's checksums, and the same file is in the public GitHub mirror at the release tag.

curl -fsSLO https://gitslice.io/releases/latest/download/install.sh
curl -fsSL https://gitslice.io/releases/latest/download/checksums.txt | grep ' install.sh$' | sha256sum -c -
tag=$(curl -fsSI https://gitslice.io/releases/latest | sed -n 's#^[Ll]ocation: .*/tag/##p' | tr -d '\r')
curl -fsSL "https://raw.githubusercontent.com/gitslice-io/gitslice/$tag/web/public/install.sh" | cmp - install.sh
less install.sh && sh install.sh

Or with Homebrew (macOS and Linux)

brew install gitslice-io/tap/gitslice

Installs gs with its shell completions. Upgrade it with brew upgrade gitslice. Ghostscript also installs a gs command, so the two cannot be installed together with Homebrew.

Option B — go install

go install gitslice.io/gitslice/cmd/gs@latest

Make sure your Go bin directory is on PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Option C — build from source

git clone https://gitslice.io/git/gitslice/gitslice.git gitslice-src
cd gitslice-src/gitslice/gitslice
make install   # builds gs (and gitslice-server) into your Go bin

Gitslice hosts its own source in the public slice gitslice/gitslice. Clones keep the account-rooted layout, so the module sits under gitslice/gitslice/.

Verify

gs defaults to the hosted endpoint, so you can sign in right away. Point at a different server with --server or GS_SERVER_ADDR.

gs version
gs auth login
gs auth status

Auth

gs auth login: Sign in to an account.
gs auth status: Show the active session.
gs auth logout: Clear local authentication.
gs auth token: Print an auth token for local tooling.
gs auth register-agent --username <name> --email <owner>: Agents: sign up with no browser and save an API key.
gs auth keys create --agent <name>: Owners: make a new API key for an agent that lost its key (printed once). gs auth keys list and revoke manage the rest.
gs auth use-key: Agents: sign in with a key an owner created, read from stdin or --key-file.
gs claims list: List agents registered with your verified email.
gs claims accept <agent-id>: Become a co-owner of an agent's account.

Setup and troubleshooting

gs doctor [account/slice]: Check version, server, sign-in, workspace and slice access; says how to fix each problem.
gs upgrade: Install the latest release (--check only reports). gs also says once a day when one is out.
gs completion bash|zsh|fish: Print a shell completion script; gs completion <shell> --help says how to load it.
gs feedback "<message>" --category bug|idea|docs: Tell the Gitslice team what went wrong or what would help; gs feedback list --mine shows their answers.

Workspace and source

gs init <account>:<slice>: Create a workspace for one slice: checks every file out into the current empty directory.
gs init --lazy <account>:<slice> [dir]: Create a lazy workspace instead (Linux and macOS, with FUSE): the slice is mounted at dir in seconds (2.6 s for 4,500 files, cold), a file's content is fetched the first time something reads it (each first read is a server round trip; a walk of the whole tree, such as grep or a build, is read ahead of, and gs fetch first is fastest for work that reads everything), and your edits stay on this machine until gs create. Every other command works as in a checkout; gs sync and changeset switching move the mount without fetching. --prefetch <glob> warms files in the background; --read-only refuses writes.
gs workspace delete [dir]: Delete a workspace from this machine: unmount a lazy one and delete its state, or remove a checkout. Refuses while it has edits no changeset holds; --force discards them.
gs mount <dir>: Mount a lazy workspace again after gs unmount or a reboot, with its edits.
gs unmount <dir>: Unmount a lazy workspace; its edits are kept. One background process serves all your lazy workspaces and exits when the last is unmounted.
gs mount list: List your lazy workspaces, mounted or not (gs mount status shows fetches and errors, gs mount discard deletes one).
gs fetch [path...]: Fetch a lazy workspace's files ahead of time, for offline work or a build.
gs restore <path>... | --all: Drop local edits in a lazy workspace.
gs checkpoint [-m <message>]: Save a lazy workspace's edits on this machine, to come back to; nothing is uploaded. gs checkpoint list shows them, newest first. gs takes one by itself before sync, switch, restore and rewind.
gs rewind [checkpoint]: Put a lazy workspace's edits back as they were at a checkpoint (by default the newest that differs from now). What it replaces is checkpointed first, so a rewind can be undone.
gs fork <checkpoint> <dir>: Mount a new lazy workspace showing a checkpoint, on the base it was taken on, to try a second approach side by side.
gs shell: Open the server-backed file shell.
gs status: Show pending workspace edits.
gs diff: Inspect pending content changes, three lines of context around each (-U N to change).
gs ci: Run the slice's checks against your pending edits, locally.
gs log: Read recent accepted history.
gs blame <path>: Which commit and changeset last changed each line (--lines 10,20, --json).
gs show <commit>: Inspect an accepted native commit.

File operations

gs fs ls <path>: List server files.
gs fs cat <path>: Read a server file.
gs fs upload <local> <path>: Upload and land local content; prints the changeset link.
gs fs write <path> --text <t> --no-submit: Open the change as a changeset for review instead of landing it.
gs fs mkdir <path>: Create a directory.

Changesets

gs create --message <title>: Create a changeset from pending edits; prints its link.
gs create --all --message <title> --submit: Create and land in one step: waits for required checks, then submits.
gs create --message <title> --description-file <file>: Give the changeset a Markdown description; the title stays one line.
gs cs edit --title <title> --description <text>: Change a draft changeset's title or description.
gs modify: Create a new patchset on the active changeset.
gs diff: Review workspace or changeset content.
gs submit: Submit for validation and publish.
gs deps: Inspect dependent changesets.

Slices

gs slice list: List account slices, and those shared with you.
gs slice share <slice> <username>: Give a person or agent a role on one slice (--role reader|writer|admin).
gs slice members <slice>: Who the slice is shared with; gs slice unshare and gs slice leave end it.
gs slice create: Create a slice definition.
gs slice update: Change included paths or policy (e.g. --required-check).
gs slice rename <slice> <new-name>: Rename a slice. The old name keeps resolving and stays reserved.
gs slice archive <slice>: Hide a slice from listings and make it read-only (gs slice unarchive restores it).
gs slice set-ci-daemon: Designate the daemon that runs out-of-slice checks: one of yours, or one its owner exposed to the slice (gs agent status --slice).
gs slice history: Inspect slice definition versions.

Secrets

gs secret create <NAME> --slice <slice>: Store a value (read from stdin) for the CI checks of some slices, or --all-slices.
gs secret ls: List the account's secrets and the slices each reaches; values are never shown.
gs secret update <secret-id>: Replace the value (--value) or change the slices (--add-slice, --remove-slice).
gs secret rm <secret-id>: Delete a secret from every slice it reaches.
gs slice secret ls <slice>: The names of the secrets that reach one slice.

Webhooks

gs webhook create --url <https-url> --event <name>: Send a slice's events to an endpoint; --secret-stdin signs deliveries.
gs webhook list: List a slice's webhooks and how their last delivery went.
gs webhook ping <webhook-id>: Send a ping now and show the response.
gs webhook deliveries <webhook-id>: Recent deliveries, newest first.
gs webhook redeliver <delivery-id>: Send a delivery's event again.
gs webhook update <webhook-id>: Change the URL, events, secret or --active.
gs webhook delete <webhook-id> --yes: Delete a webhook and its history.

Agents

gs agent start: Run an agent daemon in an empty directory; with --ci it runs your slices' checks.
gs agent status: List your agent daemons, and those of agents you own, with their status and the slices that use each as their CI daemon.
gs agent expose <daemon> <slice>: Let a slice's owners choose your daemon as its CI daemon; gs agent unexpose withdraws it.
gs agent rename <daemon> <name>: Name a daemon; the name shows in the web app, slice settings and check runs. --clear drops it.
gs agent stop: How to stop a running daemon (Ctrl-C).