CLI

The gritz binary holds the CLI, the server, the runner and the tools that run inside sandboxes. This page lists every subcommand and flag; Using the CLI shows how to use the everyday ones.

gritz [--help] [--version] <command> [flags] [args]

--help (-h) works on every command, and --version (-v) prints the version, as gritz version does. Where a flag has an environment variable, the flag wins when both are set.

Authentication

The commands that talk to a server get their API key in one of two ways:

• gritz task, gritz logs and gritz shell read it from config.json in the config directory, as {"token": "xat_..."}. See Configuration.
• gritz mcp and gritz notify take it from --token or GRITZ_TOKEN.
• gritz runner reads config.json too, unless --key or GRITZ_API_KEY is set.

The config directory is GRITZ_CONFIG_DIR if set, otherwise gritz under the user config directory (~/.config/gritz on Linux). Every --server flag defaults to https://gritz.dev.

Tasks

gritz task create

Creates a task and starts it, then prints it as JSON.

Flag	Environment	Default
--runner, -r			The runner to run on. Required.
--workspace, -w		default	The workspace.
--instruction, -i			An instruction. Repeat it for several.
--name, -n			The task’s name.
--auto-archive		0	The auto-archive delay, such as 24h. 0 is never; a negative value archives the task as soon as it finishes.
--server, -s	GRITZ_SERVER	https://gritz.dev	The server URL.

gritz task list

Prints the organisation’s 50 newest unarchived tasks as JSON.

Flag	Environment	Default
--server, -s	GRITZ_SERVER	https://gritz.dev	The server URL.

gritz task update <task-id>

Changes a task. It needs at least one of --add-instruction, --start, --name or --auto-archive.

Flag	Environment	Default
--add-instruction, -i			Add an instruction. Repeat it for several.
--start, -r			Start the task. A running task isn’t interrupted: it runs again when its current run ends.
--name, -n			Rename the task.
--auto-archive		0	Set the auto-archive delay. Every update sets it, to never when the flag is left out.
--server, -s	GRITZ_SERVER	https://gritz.dev	The server URL.

gritz logs <task-id>

Prints a task’s log.

Flag	Environment	Default
--follow, -f			Keep printing new output.
--interval		2s	How often --follow checks for new output.
--server, -s	GRITZ_SERVER	https://gritz.dev	The server URL.

gritz shell <task-id>

Opens an interactive shell in a task’s sandbox, relayed through the server. See A shell in the sandbox.

Flag	Environment	Default
--server, -s	GRITZ_SERVER	https://gritz.dev	The server URL.

Clients

gritz mcp

Runs a local MCP server over stdio, for Claude Code, Cursor and other MCP clients. See MCP.

Flag	Environment	Default
--token	GRITZ_TOKEN		The API key. Required.
--server, -s		https://gritz.dev	The server URL.
--auto-archive			The auto-archive delay for tasks created without an auto_archive argument.
--channel		off	Push task updates into the Claude Code session as channel messages, and add the channel_mute, channel_unmute and channel_muted tools.

gritz notify

Shows a desktop notification each time one of the organisation’s tasks completes, fails or is cancelled, until stopped.

Flag	Environment	Default
--token	GRITZ_TOKEN		The API key. Required.
--server, -s		https://gritz.dev	The server URL.
--title		gritz	The notifications’ title.

Server and runner

gritz server

Runs the server. Its flags are described in Server.

Flag	Environment	Default
--addr, -a		:6464
--db, -d	GRITZ_DATABASE_URL
--base-url	GRITZ_BASE_URL
--cors	GRITZ_CORS	off
--auth-domain	GRITZ_AUTH_DOMAIN
--auth-client-id	GRITZ_AUTH_CLIENT_ID
--auth-client-secret	GRITZ_AUTH_CLIENT_SECRET
--auth-scopes	GRITZ_AUTH_SCOPES	openid,profile,email,offline_access
--auth-skip-nonce-verify	GRITZ_AUTH_SKIP_NONCE_VERIFY	off
--auth-encryption-key	GRITZ_AUTH_ENCRYPTION_KEY	generated at start
--auth-app-key	GRITZ_AUTH_APP_KEY	generated at start
--no-auth		off
--github-app-id	GRITZ_GITHUB_APP_ID
--github-app-slug	GRITZ_GITHUB_APP_SLUG
--github-client-id	GRITZ_GITHUB_CLIENT_ID
--github-client-secret	GRITZ_GITHUB_CLIENT_SECRET
--github-webhook-secret	GRITZ_GITHUB_WEBHOOK_SECRET
--github-private-key	GRITZ_GITHUB_APP_PRIVATE_KEY
--atlassian-client-id	GRITZ_ATLASSIAN_CLIENT_ID
--atlassian-client-secret	GRITZ_ATLASSIAN_CLIENT_SECRET
--archive-poll	GRITZ_ARCHIVE_POLL	0 (off)
--archive-batch	GRITZ_ARCHIVE_BATCH	100
--schedule-poll	GRITZ_SCHEDULE_POLL	10s
--schedule-batch	GRITZ_SCHEDULE_BATCH	100

gritz runner

Runs a runner. Its flags are described in Runner.

Flag	Environment	Default
--server, -s	GRITZ_SERVER	https://gritz.dev
--key, -k	GRITZ_API_KEY	config.json
--workspaces, -w		workspaces.yaml in the config directory
--id	GRITZ_RUNNER_ID	the hostname
--backend	GRITZ_BACKEND	docker
--concurrency		5
--state-db	GRITZ_STATE_DB	/var/lib/gritz/runner.db
--poll		30s
--lambda-microvm-region	GRITZ_LAMBDA_MICROVM_REGION	the AWS SDK’s region
--local-root	GRITZ_LOCAL_ROOT
--debug		off

--backend also accepts local, which runs agents directly on the runner’s host, without isolation, in sandboxes under --local-root. It is for tests and development.

gritz download

Downloads the prebuilt driver binaries a runner needs from the latest GitHub release. See Driver binaries.

Flag	Default
--github-repo	gritzapp/gritz	The repository to download from, as owner/repo.

gritz workspaces

Loads a workspace config, with its ${env:} and ${sh:} expansions, and prints the result, to check it before restarting a runner.

Flag	Default
--config, -c	workspaces.yaml	The file to load, relative to the current directory.

gritz containers

Lists the gritz containers on this host’s Docker, running or not.

Flag
--prune	Remove every stopped gritz container instead.

gritz prune

Removes the stopped gritz containers on this host’s Docker whose tasks are archived.

Flag	Default
--server, -s	https://gritz.dev	The server to look the tasks up on.

gritz version

Prints the version.

Inside the sandbox

These commands run inside a task’s sandbox. The runner and the workspace config start them; you don’t run them yourself.

gritz driver

The driver server, which the runner’s backend starts in each sandbox. It runs the setup commands and the agent, and ships the task’s log.

Flag	Default
--addr	:8080	The TCP address or unix:///path to serve on.
--prefix	/	A directory prepended to every path the driver uses in the sandbox.
--aws-lambda-hooks	off	Also answer the Lambda MicroVM lifecycle hooks.
--aws-lambda-validate		An executable to run on the Lambda MicroVM image’s validate hook, to warm the snapshot. Needs --aws-lambda-hooks.

gritz tool agent-mcp

The MCP server behind the agent tools. The runner adds it to every agent’s MCP config.

Flag
--task, -t	The task ID. Required.
--runner, -r	The runner ID. Required.
--workspace, -w	The workspace. Required.
--token	The task’s token. Required.
--server, -s	The server URL. Defaults to https://gritz.dev.
--capability	A capability of the task. Repeat it for several.

gritz tool github-mcp

An MCP server over stdio that forwards to GitHub’s MCP server with GitHub App installation tokens, rotating them before they expire. For workspaces with the github_token capability; see GitHub credentials for agents.

Flag	Environment	Default
--server	GRITZ_SERVER	https://gritz.dev	The server URL.
--token	GRITZ_TOKEN		The task’s token.
--url		https://api.githubcopilot.com/mcp/	GitHub’s MCP endpoint.
--min-ttl		5m	Rotate to a new token when the current one has less than this left.

Hidden commands

gritz --help doesn’t list these two:

• gritz tool git-credential: a git credential helper that answers with GitHub App installation tokens, for workspaces with the github_token capability. It takes --server (GRITZ_SERVER) and --token (GRITZ_TOKEN). Configure it with git config --global credential.https://github.com.helper "!gritz tool git-credential".
• gritz tool proxy --addr <addr>: connects its stdin and stdout to a TCP address or unix:///path. The Docker backend uses it to reach the driver’s socket.