Commands

auth

Manage authentication.

guild auth login              # Log in via browser OAuth
guild auth logout             # Remove stored token
guild auth status             # Show authentication state
guild auth token              # Print the current auth token

agent

Build and manage agents.

Development workflow

# Initialize the current directory as a new agent
guild agent init
guild agent init --name my-agent
guild agent init --name my-agent --template LLM
guild agent init --name my-agent --category development --tags "code-review,testing"
guild agent init --fork <agent-id>   # Start from an existing agent

Templates: LLM (default), AUTO_MANAGED_STATE, BLANK

# Save changes (commits code and syncs with Guild)
guild agent save --message "Add rate limiting"
guild agent save --message "Fix bug" --wait       # Wait for validation
guild agent save --message "Ship it" --wait --publish  # Save and publish

# Pull remote changes into the local directory
guild agent pull

# Test the agent in the current directory
guild agent test
guild agent test "Summarize this PR: github.com/org/repo/pull/42"

# Chat with the agent you're developing
guild agent chat

guild agent save -A/--all commits only modified tracked files. New files are untracked and are not saved — stage them with git add <file> (or git add .) first.

Test

Test the agent in the current directory. guild agent test polls for the agent’s response and prints it. Use --timeout to override how long the CLI waits before the poll times out.

guild agent test                             # Test the current directory's agent
guild agent test "Summarize this PR"         # Send an initial prompt
guild agent test --timeout 300               # Wait up to 300 seconds for the response
guild agent test --resume <session-id>       # Resume an existing session

Option	Description
`--timeout <seconds>`	Seconds to wait when polling for the agent’s response (default: 180). Must be a positive integer, otherwise the command exits with code `1` and prints `Error: Invalid --timeout value: <value>`.
`--resume <session-id>`	Resume an existing session, such as one whose response poll timed out.

A poll timeout is recoverable: the session is not discarded when polling times out, so you can resume it. In --mode json, the error output includes the session ID and the resume hint guild agent test --resume <session-id>. In --mode jsonl, the timeout output includes the session ID and the same resume hint, and the command continues to the next input line.

Chat

Chat with the agent you’re developing from inside the agent directory. By default, guild agent chat creates an ephemeral build from your local files and starts a new session.

guild agent chat                             # Interactive chat using an ephemeral build
guild agent chat "Summarize this PR"         # Start with an initial prompt
guild agent chat --resume <session-id>       # Resume an existing session
guild agent chat --mode json                 # Use JSON input/output mode
guild agent chat --mode jsonl                # Use JSONL input/output mode
guild agent chat --agent-version <id>        # Chat with a specific existing version
guild agent chat --no-cache                  # Force a fresh ephemeral build

Ephemeral builds are the default. guild agent chat builds an agent version from your local files, and unchanged files reuse the cached ephemeral build.

Ephemeral builds include only files tracked by Git. guild agent test and guild agent chat upload files that are already committed or staged with git add. New untracked files are ignored until you stage them with git add. Modified tracked files still upload their working-tree content, so you can test uncommitted changes to existing files without committing them first.

Option	Description
`--resume <session-id>`	Resume an existing session. Works in interactive, `--mode json`, and `--mode jsonl` modes.
`--mode <format>`	Set the input and output mode. Accepts `json` or `jsonl`.
`--agent-version <id>`	Chat with a specific existing version, given as a UUID or version number, instead of the default ephemeral build.
`--no-cache`	Skip the ephemeral build cache and force a fresh build.

--resume <session-id> works in all modes: interactive, --mode json, and --mode jsonl. Resuming a session skips version resolution and ephemeral builds entirely, because the resumed session already pins its agent version and workspace. --workspace and --agent-version are ignored when you resume. In --mode json and --mode jsonl, resuming appends your input to the specified session as a new user message instead of creating a new session. The CLI reports the resumed session’s ID, and response polling only considers events created after your message. If the session ID does not exist or you cannot access it, guild agent chat exits with code 1 without building the agent and prints:

Cannot resume session '<id>': it does not exist or you do not have access to it. List your sessions with: guild session list

Publishing

guild agent publish              # Publish the latest draft version
guild agent publish --wait       # Wait for validation before publishing
guild agent publish --wait --timeout 300  # Specify validation/publish wait timeout (default: 300s)
guild agent unpublish            # Unpublish the latest published version
guild agent versions             # List all versions

Option	Description
`--timeout <seconds>`	Seconds to wait for validation/publish to complete when using `--wait` (default: 300). Must be a positive integer.

Discovery and management

guild agent list                             # List your agents
guild agent search "code review"             # Search published agents
guild agent get <agent-id>                   # Get agent details
guild agent create <name>                    # Create an agent record
guild agent update <agent-id> --description "New description"
guild agent clone <agent-id>                 # Clone an agent's code locally
guild agent code <agent-id>                  # Fetch published code
guild agent code <agent-id> --draft          # Include draft versions

Capabilities

Show an agent’s resolved tools, grouped by their source unit — integrations, sub-agents, and built-in or legacy services. Each tool is marked read, write, or unknown. The unknown marker is shown separately from read because an unclassified tool may write.

guild agent capabilities                       # Show tools for the current directory's agent
guild agent capabilities <identifier>          # Show tools for a specific agent (ID or myorg~my-agent)
guild agent capabilities --version <id>        # Use a specific version instead of the latest published
guild agent capabilities --output json         # Emit the raw JSON payload

The [identifier] argument is optional. It accepts an agent ID or a full name like myorg~my-agent, and defaults to the agent in the current directory. --version <id> overrides the default latest published version. --output json emits the raw payload with version_id, tools, and access fields. The command requires authentication; run guild auth login first. Example output:

Integration: github
  read     github_get_pull_request
  write    github_create_issue

Sub-agent: guildai/triage-agent
  unknown  run_triage

Built-in: ui
  unknown  ui_prompt

With --output json, the command emits a machine-readable payload instead:

{
  "version_id": "ver_01ABCDEF",
  "tools": [ ... ],
  "access": {
    "github_get_pull_request": "read",
    "github_create_issue": "write",
    "run_triage": "unknown"
  }
}

workspace

Manage workspaces and their contents.

guild workspace list                    # List all accessible workspaces
guild workspace create <name>           # Create a new workspace
guild workspace get <identifier>        # Get workspace details
guild workspace select                  # Set the default workspace (interactive)
guild workspace select <id-or-name>     # Set the default workspace directly
guild workspace current                 # Show current default workspace
guild workspace clear                   # Remove the default workspace setting

After a successful global workspace selection, guild workspace select prints to stderr: To clear the default, run: guild workspace clear. Pass --quiet to suppress it.

Chat

Start a conversation with an agent.

guild workspace chat                                   # Interactive chat with the Guild assistant
guild workspace chat "Summarize my open PRs"           # Start with an initial message
guild workspace chat --agent <identifier>              # Chat with a specific agent
guild workspace chat --workspace <identifier>          # Use a specific workspace
guild workspace chat --once "What is 2 + 2?"           # One-shot: send message and exit
guild workspace chat --resume <session-id>             # Resume a previous session (interactive or --once mode)
guild workspace chat --once --resume <session-id> "Another question"   # Resume a session in one-shot mode

To chat with the agent you’re currently developing, use guild agent chat from inside the agent directory.

Workspace agents

guild workspace agent list                    # List agents installed in workspace
guild workspace agent add <identifier>        # Install an agent
guild workspace agent remove <identifier>     # Remove an agent

Workspace context

guild workspace context list <workspace-id>                      # List context versions
guild workspace context get <workspace-id> <context-id>          # Get a version
guild workspace context edit <workspace-id>                      # Edit in $EDITOR, creates draft
guild workspace context edit <workspace-id> --from <context-id>  # Edit from a specific version
guild workspace context publish <workspace-id> <context-id>      # Publish a draft

clear

Remove the default workspace setting from configuration.

guild workspace clear

Behavior depends on where you run the command:

In an agent directory (contains guild.json): removes workspace_id from guild.json and prints ✓ Cleared workspace setting for this agent.
Outside an agent directory: removes default_workspace and default_workspace_name from ~/.guild/config.json and prints ✓ Default workspace cleared.

If no default workspace is set, the command prints No default workspace was set. to stderr and exits successfully — it is not an error. Exit codes: 0 on success or no-op; 1 on filesystem error only.

chat

Open The Smith, Guild’s built-in support agent, in an interactive chat session.

guild chat        # Open The Smith

To chat with the generic workspace assistant instead, use guild workspace chat.

session

Inspect sessions in a workspace.

guild session list                           # List sessions in the default workspace
guild session list --workspace <id>          # Specify a workspace
guild session list --type chat               # Filter by type: chat, webhook, time, agent_test
guild session get <session-id>               # Get session details
guild session events <session-id>            # Stream session events
guild session tasks <session-id>             # List tasks in a session
guild session send <session-id> <message>    # Send a user message to a session

api

Call any Guild REST API endpoint directly. guild api is an authenticated escape hatch that mirrors guild session get and acts as a CLI counterpart to the MCP data tools. Use it to reach endpoints that do not have a dedicated command yet.

guild api GET /me                            # Retrieve your user details
guild api GET /workspaces                    # List your workspaces
guild api POST /workspaces --data '{"name":"demo"}'  # Send a JSON request body

The command validates your session token, checks the HTTP method, and parses any --data JSON before calling the Guild REST API. It prints the raw JSON response to stdout.

Argument	Description
`<method>`	HTTP method. One of `GET`, `POST`, `PATCH`, `PUT`, or `DELETE`.
`<path>`	API endpoint path, such as `/me` or `/workspaces`.

Option	Description
`--data <json>`	Request body as a JSON string.

trigger

Automate agent execution. See Triggers for a full guide.

guild trigger list                           # List triggers in the default workspace
guild trigger get <trigger-id>               # Get trigger details
guild trigger sessions <trigger-id>          # List sessions spawned by a trigger

# Create a webhook trigger
guild trigger create --type webhook --service SLACK --event app_mention --agent <identifier>

# Create a time trigger
guild trigger create --type time --frequency DAILY --time 09:00 --agent <identifier>

guild trigger update <trigger-id> --time 10:00
guild trigger activate <trigger-id>
guild trigger deactivate <trigger-id>

integration

Build and manage custom integrations.

Discovery and management

guild integration list                        # List integrations
guild integration list --search "deploy"      # Search by name or description
guild integration list --published            # Only show published integrations
guild integration search <query>              # Search integrations
guild integration search <query> --sort newest  # Sort by: updated, newest, name
guild integration search <query> --published  # Only show published integrations
guild integration search <query> --limit 10 --offset 20  # Paginate results
guild integration get <id_or_name>            # Get integration details

Creating and updating

# Create a new integration with API key auth
guild integration create my-service \
  --base-url https://api.example.com \
  --auth-scheme api-key \
  --description "Connect to the Acme API"

# Create with OAuth
guild integration create my-oauth-service \
  --base-url https://api.example.com \
  --auth-scheme oauth \
  --install-url https://example.com/oauth/authorize \
  --token-url https://example.com/oauth/token \
  --client-id <id> --client-secret <secret> \
  --scopes "read,write"

# Update an existing integration
guild integration update myorg~my-service --description "Updated description"
guild integration update myorg~my-service --base-url https://api.v2.example.com

Guild validates the --base-url, --install-url, and --token-url values to prevent server-side request forgery (SSRF). Private network ranges, loopback addresses (such as localhost or 127.0.0.1), and internal DNS names are blocked. For local development, expose your service using a tunneling tool such as ngrok or Localtunnel and use the public URL.

Connecting credentials

guild integration connect myorg~my-service                  # Interactive prompt
guild integration connect myorg~my-service --token <value>  # Non-interactive

Versions

guild integration version list <id_or_name>                 # List versions
guild integration version create <id_or_name>               # Create a draft version
guild integration version get <id_or_name>                  # Get latest version details
guild integration version get <id_or_name> --version-number 1.0.0

guild integration version build <id_or_name> --version-number 1.0.0   # Validate a draft
guild integration version publish <id_or_name> --version-number 1.0.0 # Publish a built version

Operations (endpoints)

# List operations on a version
guild integration operation list <id_or_name>
guild integration operation list <id_or_name> --version-number 1.0.0

# Add operations manually
guild integration operation create myorg~my-service \
  --operation list_users \
  --method GET \
  --path /users \
  --summary "List all users"

# Import operations from an OpenAPI spec
guild integration operation create myorg~my-service --openapi ./openapi.yaml

Testing

guild integration version test myorg~my-service \
  --operation list_users \
  --account my-account \
  --input-query '{"limit": 10}'

container-image

Manage container images.

guild container-image list                   # List container images
guild container-image get <image-id>         # Get details for a container image
guild container-image create <name>          # Create a container image
guild container-image modify <image-id>      # Modify an existing container image

skill

Create and manage reusable skill packages. See Skills for a full guide.

guild skill create <name>                    # Create a new skill
guild skill create <name> --overview "..."   # Create with description
guild skill get <identifier>                 # Get skill details (name or UUID)
guild skill list                             # List skills
guild skill list --search "tone"             # Search skills
guild skill search "compliance"              # Search skills by keyword
guild skill search "tone" --published        # Only show published skills
guild skill update <identifier> --overview "New description"
guild skill update <identifier> --public     # Make public (requires admin)
guild skill archive <identifier>             # Archive the skill
guild skill unarchive <identifier>           # Restore an archived skill

Versions

guild skill version create <identifier> \
  --version-number 1.0.0 \
  --description "Runtime description" \
  --body-file content.md                     # Create a version from file

guild skill version list <identifier>        # List versions
guild skill version get <version-id>         # Get version details

config

Read and write global CLI configuration.

guild config list               # Show all config values
guild config get <key>          # Read a value
guild config set <key> <value>  # Write a value
guild config path               # Show path to config file

Keys: default_workspace, debug, json, quiet

Utilities

guild doctor     # Diagnose setup issues (auth, server, workspace, git)
guild setup      # Install coding assistant skills in the current project
guild version    # Show the CLI version

Use the --simple flag with guild version to print only the bare version number followed by a newline, with no additional decoration. This makes the output easy to capture in scripts.

guild version --simple                     # Output only the version number, e.g. 0.16.0
GUILD_VERSION=$(guild version --simple)    # Capture the version in a script

CLI

auth

agent

Development workflow

Test

Chat

Publishing

Discovery and management

Capabilities

Tags

Categories

workspace

Chat

Workspace agents

Workspace context

clear

chat

session

api

trigger

integration

Discovery and management

Creating and updating

Connecting credentials

Versions

Operations (endpoints)

Testing

container-image

skill

Versions

config

Utilities

​auth

​agent

​Development workflow

​Test

​Chat

​Publishing

​Discovery and management

​Capabilities

​Tags

​Categories

​workspace

​Chat

​Workspace agents

​Workspace context

​clear

​chat

​session

​api

​trigger

​integration

​Discovery and management

​Creating and updating

​Connecting credentials

​Versions

​Operations (endpoints)

​Testing

​container-image

​skill

​Versions

​config

​Utilities

auth

agent

Development workflow

Test

Chat

Publishing

Discovery and management

Capabilities

Tags

Categories

workspace

Chat

Workspace agents

Workspace context

clear

chat

session

api

trigger

integration

Discovery and management

Creating and updating

Connecting credentials

Versions

Operations (endpoints)

Testing

container-image

skill

Versions

config

Utilities