> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Guild CLI

> Install and set up the Guild command-line interface.

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

```bash theme={null}
npm install -g @guildai/cli
```

Verify the installation:

```bash theme={null}
guild --version
```

## Authenticate

```bash theme={null}
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).

```bash theme={null}
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:

```bash theme={null}
guild workspace select
```

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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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):

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

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