> ## 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. # Commands > Reference for all Guild CLI commands. ## auth Manage authentication. ```bash theme={null} 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 ```bash theme={null} # 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 # Start from an existing agent ``` **Templates:** `LLM` (default), `AUTO_MANAGED_STATE`, `BLANK` ```bash theme={null} # 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 ` (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. ```bash theme={null} 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 # Resume an existing session ``` | Option | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--timeout ` | 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: `. | | `--resume ` | 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 `. 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. ```bash theme={null} guild agent chat # Interactive chat using an ephemeral build guild agent chat "Summarize this PR" # Start with an initial prompt guild agent chat --resume # 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 # 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 ` | Resume an existing session. Works in interactive, `--mode json`, and `--mode jsonl` modes. | | `--mode ` | Set the input and output mode. Accepts `json` or `jsonl`. | | `--agent-version ` | 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 ` 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: ```text theme={null} Cannot resume session '': it does not exist or you do not have access to it. List your sessions with: guild session list ``` ### Publishing ```bash theme={null} 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 to wait for validation/publish to complete when using `--wait` (default: 300). Must be a positive integer. | ### Discovery and management ```bash theme={null} guild agent list # List your agents guild agent search "code review" # Search published agents guild agent get # Get agent details guild agent create # Create an agent record guild agent update --description "New description" guild agent clone # Clone an agent's code locally guild agent code # Fetch published code guild agent code --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. ```bash theme={null} guild agent capabilities # Show tools for the current directory's agent guild agent capabilities # Show tools for a specific agent (ID or myorg~my-agent) guild agent capabilities --version # 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 ` 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: ```text theme={null} 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: ```json theme={null} { "version_id": "ver_01ABCDEF", "tools": [ ... ], "access": { "github_get_pull_request": "read", "github_create_issue": "write", "run_triage": "unknown" } } ``` ### Tags ```bash theme={null} guild agent tags list # List tags on the current agent guild agent tags add analytics # Add a tag guild agent tags remove analytics # Remove a tag ``` ### Categories ```bash theme={null} guild agent categories # List categories and their allowed tags ``` *** ## workspace Manage workspaces and their contents. ```bash theme={null} guild workspace list # List all accessible workspaces guild workspace create # Create a new workspace guild workspace get # Get workspace details guild workspace select # Set the default workspace (interactive) guild workspace select # 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. ```bash theme={null} 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 # Chat with a specific agent guild workspace chat --workspace # Use a specific workspace guild workspace chat --once "What is 2 + 2?" # One-shot: send message and exit guild workspace chat --resume # Resume a previous session (interactive or --once mode) guild workspace chat --once --resume "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 ```bash theme={null} guild workspace agent list # List agents installed in workspace guild workspace agent add # Install an agent guild workspace agent remove # Remove an agent ``` ### Workspace context ```bash theme={null} guild workspace context list # List context versions guild workspace context get # Get a version guild workspace context edit # Edit in $EDITOR, creates draft guild workspace context edit --from # Edit from a specific version guild workspace context publish # Publish a draft ``` ### clear Remove the default workspace setting from configuration. ```bash theme={null} 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](/platform/smith), Guild's built-in support agent, in an interactive chat session. ```bash theme={null} guild chat # Open The Smith ``` To chat with the generic workspace assistant instead, use [`guild workspace chat`](#workspace). *** ## session Inspect sessions in a workspace. ```bash theme={null} guild session list # List sessions in the default workspace guild session list --workspace # Specify a workspace guild session list --type chat # Filter by type: chat, webhook, time, agent_test guild session get # Get session details guild session events # Stream session events guild session tasks # List tasks in a session guild session send # 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. ```bash theme={null} 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 | | ---------- | --------------------------------------------------------------- | | `` | HTTP method. One of `GET`, `POST`, `PATCH`, `PUT`, or `DELETE`. | | `` | API endpoint path, such as `/me` or `/workspaces`. | | Option | Description | | --------------- | ------------------------------ | | `--data ` | Request body as a JSON string. | *** ## trigger Automate agent execution. See [Triggers](/triggers) for a full guide. ```bash theme={null} guild trigger list # List triggers in the default workspace guild trigger get # Get trigger details guild trigger sessions # List sessions spawned by a trigger # Create a webhook trigger guild trigger create --type webhook --service SLACK --event app_mention --agent # Create a time trigger guild trigger create --type time --frequency DAILY --time 09:00 --agent guild trigger update --time 10:00 guild trigger activate guild trigger deactivate ``` *** ## integration Build and manage custom integrations. ### Discovery and management ```bash theme={null} 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 # Search integrations guild integration search --sort newest # Sort by: updated, newest, name guild integration search --published # Only show published integrations guild integration search --limit 10 --offset 20 # Paginate results guild integration get # Get integration details ``` ### Creating and updating ```bash theme={null} # 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 --client-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](https://ngrok.com) or [Localtunnel](https://theboroer.github.io/localtunnel-www/) and use the public URL. ### Connecting credentials ```bash theme={null} guild integration connect myorg~my-service # Interactive prompt guild integration connect myorg~my-service --token # Non-interactive ``` ### Versions ```bash theme={null} guild integration version list # List versions guild integration version create # Create a draft version guild integration version get # Get latest version details guild integration version get --version-number 1.0.0 guild integration version build --version-number 1.0.0 # Validate a draft guild integration version publish --version-number 1.0.0 # Publish a built version ``` ### Operations (endpoints) ```bash theme={null} # List operations on a version guild integration operation list guild integration operation list --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 ```bash theme={null} guild integration version test myorg~my-service \ --operation list_users \ --account my-account \ --input-query '{"limit": 10}' ``` *** ## container-image Manage container images. ```bash theme={null} guild container-image list # List container images guild container-image get # Get details for a container image guild container-image create # Create a container image guild container-image modify # Modify an existing container image ``` *** ## skill Create and manage reusable skill packages. See [Skills](/cli/skills) for a full guide. ```bash theme={null} guild skill create # Create a new skill guild skill create --overview "..." # Create with description guild skill get # 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 --overview "New description" guild skill update --public # Make public (requires admin) guild skill archive # Archive the skill guild skill unarchive # Restore an archived skill ``` ### Versions ```bash theme={null} guild skill version create \ --version-number 1.0.0 \ --description "Runtime description" \ --body-file content.md # Create a version from file guild skill version list # List versions guild skill version get # Get version details ``` *** ## config Read and write global CLI configuration. ```bash theme={null} guild config list # Show all config values guild config get # Read a value guild config set # Write a value guild config path # Show path to config file ``` **Keys:** `default_workspace`, `debug`, `json`, `quiet` *** ## Utilities ```bash theme={null} 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. ```bash theme={null} guild version --simple # Output only the version number, e.g. 0.16.0 GUILD_VERSION=$(guild version --simple) # Capture the version in a script ```