Skip to main content
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
KeyDescription
default_workspaceDefault workspace ID used by commands
debugEnable verbose debug output
jsonAlways output JSON
quietSuppress 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

VariableDescription
GUILDCORE_URLOverride the Guild API base URL (for example, staging or self-hosted). Guild appends /api if it is missing.
GUILDCORE_PORTUse http://localhost:<PORT>/api when GUILDCORE_URL is not set.
GUILD_USE_LOCALInternal shortcut: set to 1 to use http://localhost:5001/api.
GUILD_USE_SHAREDInternal 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

VariableDescription
GUILD_WORKSPACE_IDOverride the active workspace ID without changing config files.
GUILD_OWNER_IDOverride the owner account for agent creation commands.
Workspace resolution order (before falling back to the first workspace from the API):
  1. --workspace flag on the command
  2. GUILD_WORKSPACE_ID
  3. workspace_id in local guild.json (when you are in an agent directory)
  4. default_workspace in ~/.guild/config.json

​
Other

VariableDescription
GUILD_STATE_DIROverride where the CLI stores auth state (used in tests).
GUILD_AGENT_SAVEInternal flag set during guild agent save to allow git push through the pre-push hook.
NO_COLORDisable colored CLI output.