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 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.
gs shell: Open the server-backed file shell.
gs status: Show pending workspace edits.
gs diff: Inspect pending content changes.
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 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 set-ci-daemon: Designate the daemon that runs out-of-slice checks.
gs slice history: Inspect slice definition versions.

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 a local agent daemon in an empty directory (codex runtime).
gs agent status: List your agent daemons and whether they are online.
gs agent stop: How to stop a running daemon (Ctrl-C).
gs cs conversation: Show the agent conversation that produced each patchset.