> ## 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 agent > Build, test, publish, and manage agents. 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 --agent-type GUILD_NATIVE guild agent init --fork # Start from an existing agent guild agent init --owner # Specify owner by name or ID guild agent init --name my-agent --category development --tags "code-review,testing" ``` **Templates:** `LLM` (default), `AUTO_MANAGED_STATE`, `BLANK` **Agent types:** `GUILD_TYPESCRIPT`, `GUILD_NATIVE`, `GOOSE`, `OPENCLAW`. Values are case-insensitive. Each type scaffolds a different entry point: | Agent type | Entry point | | ------------------ | ------------- | | `GUILD_TYPESCRIPT` | `agent.ts` | | `GUILD_NATIVE` | `PROMPT.md` | | `GOOSE` | `recipe.yaml` | | `OPENCLAW` | `AGENTS.md` | `--agent-type` appears only on accounts that have more than one agent type available. Omit the flag in a terminal and the CLI prompts you to choose from the types you have available. In non-interactive mode the flag is required, and omitting it exits with `Error: --agent-type is required in non-interactive mode`. `--template` is only supported for `GUILD_TYPESCRIPT`. Passing it with any other agent type exits with `Error: --template is not supported for agent type `. In non-interactive mode, `--owner` is required when your account belongs to one or more organizations. Use `guild config set default_owner ` to set a default and avoid passing `--owner` on every invocation. In interactive mode, the CLI always prompts for owner selection. ```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 guild agent save --message "Breaking change" --publish --bump major # Bump the major version when publishing guild agent save --message "Ship it" --publish --timeout 600 # Wait up to 600s for validation 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 ``` `--publish` implies `--wait`: it always waits for validation and publish to finish, then prints `Version is now published and available in the catalog.` Use `--timeout ` (default: 300) to bound that wait. The value must be a positive integer, otherwise the command prints `Invalid --timeout value` and exits with status 1. If validation is still running when the timeout elapses, the CLI tells you how to finish the job: ```text theme={null} Validation is still running. Publish once it completes: guild agent publish --wait ``` ## Forking Fork a published agent version into a new independent agent with its own repository. ```bash theme={null} guild agent fork # Fork latest published version guild agent fork : # Fork a specific version guild agent fork --name my-fork # Name the forked agent guild agent fork --owner # Assign to owner (name or ID) guild agent fork --directory ./my-fork # Clone into a specific directory guild agent fork --category # Change the forked agent's category guild agent fork --tags a,b # Set tags on the fork ``` A fork inherits the source agent's category, and its tags along with it. Pass `--category` to change it — the source tags are then dropped, and any `--tags` you pass are validated against the new category's allowed set. Inherited tags exclude Guild's own `guild:`-prefixed ones. Run `guild agent categories ` to see the allowed tags for a category. `` is an agent ID or name. If omitted, the command reads `guild.json` in the current directory. `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. ## save Commit your code and create a new version. Versions start as drafts until you publish them. ```bash theme={null} guild agent save --message "Add rate limiting" guild agent save --message "Ship it" --wait --publish # Save and publish guild agent save --message "Pin release" --version-number 2.1.0 # Set the version explicitly ``` | Option | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `--version-number ` | Set the version explicitly, overriding the default `package.json` version. Applies when saving and when publishing. | TypeScript agents derive their version from `package.json`. Goose agents (`recipe.yaml`) and Guild Native agents (`PROMPT.md`) do not use a `package.json`, so `guild agent save` skips the `package.json` version-bump checks for them. `--bump` and the default bump are no-ops for these agent types. For TypeScript agents, `guild agent save` validates `package-lock.json` to keep dependency installs reproducible. The lockfile must be tracked in Git and synchronized with `package.json`. If it is stale or invalid, the save is aborted so you can regenerate it with `npm install` and commit the result. If the lockfile is missing, untracked, or ignored, the CLI prints a warning and falls back to legacy dependency resolution. Commit `package-lock.json` alongside `package.json` so published versions install the same dependency tree. When you run `guild agent save --publish` on a Goose or Guild Native agent without `--version-number`, the CLI derives the next version automatically as a patch increment of the latest published version, or `1.0.0` when no published version exists. ## 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 guild agent test --events all # Include system and debug events ``` | 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. | | `--events ` | Event types to show (default: `user`). See [Event filtering](/cli/commands#event-filtering). | | `--mode ` | Output format: `interactive` (default), `json`, or `jsonl`. | 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. `guild agent test` runs any agent the workspace already trusts — one your account owns, or one installed in the workspace, including a public or third-party agent you added from the Hub. See [Agent-test session authorization](/platform/sessions#agent-test-session-authorization). Before it runs, the CLI checks that the files required for the agent's type are present: `agent.ts` and `package.json` for Guild TypeScript, `PROMPT.md` for Guild Native, `recipe.yaml` for Goose, and `AGENTS.md` for OpenClaw. It resolves the type from `guild.json` or the Guild API and names the file missing for that type. ## 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: `interactive` (default), `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 guild agent logs # Build/validation step logs for the latest version guild agent logs # Logs for a specific version ``` | Option | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | `--timeout ` | Seconds to wait for validation/publish to complete when using `--wait` (default: 300). Must be a positive integer. | ## Version history Render an agent's version history as git-log-style blocks, each showing the commit SHA, version number, status, validation status, relative date, and summary. ```bash theme={null} guild agent log # History for the agent in the current directory guild agent log # History for a specific agent guild agent log --limit 10 # Show at most 10 versions guild agent log --offset 20 # Skip the first 20 versions ``` The agent argument is optional and accepts an agent ID or a full name such as `myorg~my-agent`; omit it to use the agent in the current directory. | Option | Description | | -------------- | -------------------------------------------------------- | | `--limit ` | Maximum number of versions to return (default: 20). | | `--offset ` | Number of versions to skip, for pagination (default: 0). | ## diff Show what changed between your local files and a published version, as a colored unified diff. ```bash theme={null} guild agent diff # Compare against the latest published version guild agent diff 1.0.4 # Compare against a specific version ``` The version argument is optional and defaults to the latest published version. Run this from inside an agent directory — the command requires a `guild.json` and compares the same git-tracked working-tree files that `guild agent save` uploads. ## Discovery and management ```bash theme={null} guild agent list # List your agents guild agent list --workspace # List agents installed in a specific workspace guild agent search "code review" # Search published agents guild agent get # Get agent details guild agent update --public # Change visibility (--public or --private) guild agent clone # Clone an agent's code locally guild agent code # Fetch published code guild agent code --draft # Include draft versions # Archive an agent, removing it from every workspace and stopping new runs guild agent archive # Archive the agent in the current directory guild agent archive # Archive a specific agent guild agent unarchive # Restore an archived agent ``` Passing `--workspace ` to `guild agent list` lists the agents installed in that workspace rather than the platform-wide public roster. The agent argument is optional for both commands. It accepts an agent ID or a full name like `myorg~my-agent`, and defaults to the agent in `guild.json` in the current directory. See [Disabling an agent](/platform/agents#disabling-an-agent) for what archiving changes. When you pass `--workspace`, `guild agent list` returns the agents installed in that workspace, identified by ID or name. This set is specific to the workspace and excludes unrelated public agents. The `--published` flag is ignored when combined with `--workspace`, because installed agents already reference committed 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 --mode 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. `--mode 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_pulls_get write github_issues_create 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_pulls_get": "read", "github_issues_create": "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 all categories guild agent categories # Show a single category and its allowed tags ``` Run `guild agent categories` without arguments to list every category. The list table does not include a TAGS column. To see a category's allowed tags, pass its name: ```bash theme={null} guild agent categories engineering ```