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

Authenticate

guild auth login

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

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

This 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.

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
`debug`	Enable verbose debug output
`json`	Always output JSON
`quiet`	Suppress progress messages

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.

API endpoint

Variable	Description
`GUILDCORE_URL`	Override the Guild API base URL (for example, staging or self-hosted). Guild appends `/api` if it is missing.
`GUILDCORE_PORT`	Use `http://localhost:<PORT>/api` when `GUILDCORE_URL` is not set.
`GUILD_USE_LOCAL`	Internal shortcut: set to `1` to use `http://localhost:5001/api`.
`GUILD_USE_SHARED`	Internal shortcut: set to `1` to use the shared staging host (`https://shared.guildai.dev/api`).

Resolution order for the API URL: GUILD_USE_SHARED → GUILD_USE_LOCAL → GUILDCORE_URL → GUILDCORE_PORT → production default (https://app.guild.ai/api).

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.
`NO_COLOR`	Disable colored CLI output.

​Install

​Authenticate

​Select a workspace

​Set up coding assistant skills

​Verify your setup

​Configuration

​Environment variables

​API endpoint

​Workspace and owner

​Other