Guild CLI - Guild

The Guild CLI lets you build, test, and deploy agents from your terminal. It also gives your coding assistant (Claude Code, Cursor, etc.) a skill for driving agent development.

Install

npm install -g @guildai/cli

Verify the installation:

guild --version

Staying up to date

When you run the CLI in interactive mode, it checks npm for a newer @guildai/cli release. If one is available, the CLI installs it and re-runs your command against the updated version. This check runs at most once every 4 hours.

Automatic updates are available in Guild CLI 0.22.0 and later.

Auto-update is enabled by default. To disable it, set the GUILD_AUTO_UPDATE environment variable or turn off the auto_update config setting:

export GUILD_AUTO_UPDATE=0           # Disable for the current shell
guild config set auto_update false   # Disable persistently

GUILD_AUTO_UPDATE overrides the auto_update config setting whenever it’s set to a non-empty value. The two also accept different values: the environment variable only recognizes 0 or false (case-insensitive) as disabling it — anything else, including strings like no, leaves auto-update on. The config key accepts the fuller set of booleans (true/false, yes/no, on/off, 1/0).

Authenticate

guild auth login

This opens a browser window to complete OAuth authentication. Guild prefers your system’s secure credential store (Keychain on macOS, Credential Manager on Windows, libsecret on Linux).

If no OS keyring is present, such as on a headless Linux host, Guild prints a warning and falls back to a file-based store. It writes the token to auth-token.json in the global config directory (~/.guild by default, or the path set by GUILD_CONFIG_DIR) with 0600 permissions, restricting read and write access to your user only.

guild auth status   # Check authentication state
guild auth logout   # Remove stored token

Select a workspace

Most commands run in the context of a workspace. Set a default so you don’t have to specify it every time:

guild workspace select

This prompts you to choose from your available workspaces and saves your selection to ~/.guild/config.json.

guild workspace current   # Show the active default workspace

Set up coding assistant skills

If you use Claude Code or another coding assistant, run guild setup in your project to install development skills:

guild setup

guild setup previews the files it will write, then prompts you to choose a coding assistant — Claude Code, Codex, or Gemini. Pass --provider <claude|codex|gemini> to select one without the prompt, or --yes to accept the previewed actions without confirming. Choosing Claude Code creates .claude/skills/ files that give your coding assistant knowledge of the Guild SDK, CLI workflow, and agent development patterns. Use --force to update existing skill files, and --claude-md to also generate a CLAUDE.md template. For Codex, add --codex to write .agents/skills/guild-agent-dev/SKILL.md instead, and --agents-md to also generate an AGENTS.md template. For Gemini, select the gemini provider and add --gemini-md to also generate a GEMINI.md template. The template flags are mutually exclusive: pass at most one, matched to the selected assistant.

Verify your setup

guild doctor

doctor checks authentication, server connectivity, your default workspace, and git configuration, and reports any issues with suggested fixes.

Configuration

Global config is stored in ~/.guild/config.json. Use guild config to read and write it:

guild config list                    # Show all config values
guild config get default_workspace   # Read a value
guild config set debug true          # Set a value

Key	Description
`default_workspace`	Default workspace ID used by commands
`default_owner`	Default owner (personal account or org) for `guild agent init` and `guild agent fork`.
`debug`	Enable verbose debug output
`json`	Always output JSON. Equivalent to `guild --mode json`.
`quiet`	Suppress progress messages
`telemetry`	CLI telemetry: `enabled` or `disabled`.
`auto_update`	Automatic CLI updates on interactive launch: `true` or `false`. Defaults to `true`.

Local config (guild.json) is written to your agent directory when you run guild agent init and identifies the agent to the CLI.

Environment variables

You can override CLI behavior with environment variables. This is useful in CI/CD pipelines and scripts.

Workspace and owner

Variable	Description
`GUILD_WORKSPACE_ID`	Override the active workspace ID without changing config files.
`GUILD_OWNER_ID`	Override the owner account for agent creation commands.

Workspace resolution order (before falling back to the first workspace from the API):

--workspace flag on the command
GUILD_WORKSPACE_ID
workspace_id in local guild.json (when you are in an agent directory)
default_workspace in ~/.guild/config.json

Other

Variable	Description
`GUILD_STATE_DIR`	Override where the CLI stores auth state (used in tests).
`GUILD_CONFIG_DIR`	Overrides the path to the global configuration directory (defaults to `~/.guild/`).
`GUILD_AGENT_SAVE`	Internal flag set during `guild agent save` to allow git push through the pre-push hook.
`GUILD_AUTO_UPDATE`	Set to `0` or `false` to disable the automatic check for a newer CLI version on launch.
`NO_COLOR`	Disable colored CLI output.

Telemetry

The CLI reports usage telemetry linked to your Guild account: command names and flag names only — never flag values, arguments, or file contents. Telemetry is on by default and you can turn it off with an environment variable or a config setting.

Telemetry opt-out and the first-run disclosure notice are available in Guild CLI 0.18.0 and later.

Opt out

Variable	Description
`GUILD_TELEMETRY`	Set to `0` or `false` to disable telemetry. Any other non-empty value forces it on, overriding the config setting.
`DO_NOT_TRACK`	Set to any non-empty value to disable telemetry, per the consoledonottrack.com convention.

Or persist the choice in config:

guild config set telemetry disabled   # Opt out
guild config set telemetry enabled    # Opt back in
guild config get telemetry            # Show the current setting

The telemetry key accepts only enabled or disabled. Precedence is GUILD_TELEMETRY, then DO_NOT_TRACK, then the config key — so an opted-out shell overrides a stored preference, and GUILD_TELEMETRY=1 overrides a stored disabled.

First-run notice

The first time the CLI runs in interactive output mode it prints a one-time disclosure to stderr, then writes an empty marker file named telemetry-notice-shown in the global config directory (~/.guild/ unless GUILD_CONFIG_DIR is set) so it appears exactly once.

“Interactive output mode” excludes --quiet and machine-readable modes such as --mode json, as well as non-TTY contexts like CI/CD pipelines. A run that suppresses the notice defers it to the next interactive invocation rather than skipping it.

​Install

​Staying up to date

​Authenticate

​Select a workspace

​Set up coding assistant skills

​Verify your setup

​Configuration

​Environment variables

​Workspace and owner

​Other

​Telemetry

​Opt out

​First-run notice

Install

Staying up to date

Authenticate

Select a workspace

Set up coding assistant skills

Verify your setup

Configuration

Environment variables

Workspace and owner

Other

Telemetry

Opt out

First-run notice