CLI reference

garage commands, options, and environment variables.

Install the CLI with:

npm install --global @thegarage/cli

Run garage <command> --help for the arguments and options of one command. Every command accepts --json. JSON is also the default format when stdout is not a terminal.

Global options

Option	Description
`--json`	Print structured output
`--repo <name>`	Use this repository for the current command

Environment variable	Description
`GARAGE_API_KEY`	Use this API key instead of the stored credential
`GARAGE_REPO`	Set the default repository
`GARAGE_ANON_ID`	Set the anonymous repository owner identity
`GARAGE_SERVER_URL`	Target this server instead of the stored default

garage stores a separate credential for each server. A command that targets one server therefore never uses the credential of another server. Sign in again when you change GARAGE_SERVER_URL.

A repository name is a bare name in the active organization. Switch organizations with garage org switch <slug>. See Organizations and repository names for how a bare name resolves to one repository.

Setup and diagnostics

Command	Description
`garage setup`	Sign in, select an organization, and configure Git
`garage login`	Sign in without changing Git configuration
`garage auth status`	Show authentication and organization state
`garage auth logout`	Revoke and remove the stored credential
`garage doctor`	Check authentication, server access, and Git setup

garage setup --no-browser does not open a local browser. garage setup --no-credential-helper skips the global Git credential configuration.

Initialize a project

garage init [name] [options]

Creates a repository in the active organization. It also configures the current directory to push to that repository.

Option	Description
`--default-branch <name>`	Set the default branch; defaults to `main`
`--gitignore` / `--no-gitignore`	Enable or skip `.gitignore` creation
`--link-existing`	Connect to an existing repository with this name
`--yes`, `-y`	Accept the `.gitignore` prompt

The command refuses a directory with commits or a non-garage origin. See Initialize an empty project for the complete procedure.

Repository commands

Command	Description
`garage repos create <name>`	Create a repository
`garage repos import [name]`	Import a GitHub repository
`garage repos get <name>`	Show repository details
`garage repos list`	List repositories in the active organization
`garage repos delete <name>`	Delete a repository
`garage clone <name> [dir]`	Clone and configure Git credentials

garage repos create hello-world --default-branch main
garage repos import site --from https://github.com/acme/site.git
garage clone hello-world
garage repos delete hello-world --yes

Repository shares

Shares grant time-limited read or write access to one repository.

Command	Description
`garage share <repo>`	Create a share
`garage share create <repo>`	Create a share explicitly
`garage share list`	List shares you created
`garage share revoke <share-id>`	Revoke a share

--role accepts read or write. It defaults to read. The default share lifetime is seven days. The accepted range is 60 seconds through 30 days. --print shows the requested share, but it does not create the share.

The returned URL is a bearer credential. Keep it private. Revoke it when you no longer need it.

Anonymous repositories

Command	Description
`garage anon create`	Create a repository
`garage anon clone <name>`	Clone a repository
`garage anon list [name]`	List repositories or show one
`garage anon share <name>`	Manage read or write shares
`garage anon delete <name>`	Delete a repository
`garage anon status`	Show the local anonymous identity

The default repository lifetime is 24 hours. The accepted range is 60 seconds through 72 hours. An anonymous share cannot outlive its repository.

Organizations and API keys

Command	Description
`garage org list`	List your organizations
`garage org switch <slug>`	Change the active organization
`garage keys create <name>`	Create a scoped API key
`garage keys list`	List API keys
`garage keys delete <id-or-name>`	Delete an API key

garage keys create requires at least one --scope. Repeat the option to request more than one scope. --ttl <duration> sets the key lifetime, and the minimum lifetime is 24h. A key never expires when you omit --ttl.

garage keys create ci --scope repos:read --scope git:access --ttl 90d

garage keys delete accepts a key id. It also accepts a name that matches exactly one key.

Common scopes are repos:read, repos:write, git:access, orgs:read, and keys:read. The HTTP API reference lists every accepted scope.

Agent registration

Command	Description
`garage agent register`	Start a registration
`garage agent refresh`	Exchange the stored assertion for a fresh API key
`garage agent list`	List connected agents
`garage agent revoke <registration-id>`	Revoke a registration and its keys

See Set up with a coding agent for the signup and claim flow.

Extensions

Command group	Subcommands
`garage ext`	`new`, `build`, `promote`
`garage runs`	`dispatch`, `list`, `get`, `logs`
`garage tools`	`list`, `run`
`garage records`	`list`, `get`, `create`, `update`, `delete`
`garage events`	`tail`
`garage webhooks`	`list`, `get`, `secret`, `rotate`, `enable`, `disable`, `deliveries`, `redeliver`
`garage daemons`	`list`, `enable`

These commands are experimental. See the extension reference for the source formats.