guild agent - Guild

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 --agent-type GUILD_NATIVE
guild agent init --fork <agent-id>        # Start from an existing agent
guild agent init --owner <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 <agent-type>.

In non-interactive mode, --owner is required when your account belongs to one or more organizations. Use guild config set default_owner <name-or-id> to set a default and avoid passing --owner on every invocation. In interactive mode, the CLI always prompts for owner selection.

# 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 <seconds> (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:

Validation is still running. Publish once it completes:
  guild agent publish <agent-id> --wait

Forking

Fork a published agent version into a new independent agent with its own repository.

guild agent fork <identifier>                        # Fork latest published version
guild agent fork <identifier>:<version-id>           # Fork a specific version
guild agent fork <identifier> --name my-fork         # Name the forked agent
guild agent fork <identifier> --owner <owner>        # Assign to owner (name or ID)
guild agent fork <identifier> --directory ./my-fork  # Clone into a specific directory
guild agent fork <identifier> --category <name>       # Change the forked agent's category
guild agent fork <identifier> --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 <category> to see the allowed tags for a category. <identifier> 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 <file> (or git add .) first.

save

Commit your code and create a new version. Versions start as drafts until you publish them.

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

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
guild agent test --events all                # Include system and debug events

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.
`--events <types>`	Event types to show (default: `user`). See Event filtering.
`--mode <format>`	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 <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.

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.

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.

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: `interactive` (default), `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
guild agent logs                 # Build/validation step logs for the latest version
guild agent logs <identifier> <version-id>  # Logs for a specific version

Option	Description
`--timeout <seconds>`	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.

guild agent log                              # History for the agent in the current directory
guild agent log <agent-id>                   # 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 <n>`	Maximum number of versions to return (default: 20).
`--offset <n>`	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.

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

guild agent list                             # List your agents
guild agent list --workspace <id>            # List agents installed in a specific workspace
guild agent search "code review"             # Search published agents
guild agent get <agent-id>                   # Get agent details
guild agent update <agent-id> --public       # Change visibility (--public or --private)
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

# 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 <agent-id>               # Archive a specific agent
guild agent unarchive <agent-id>             # Restore an archived agent

Passing --workspace <id> 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 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.

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 --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 <id> 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:

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:

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

​Development workflow

​Forking

​save

​test

​chat

​Publishing

​Version history

​diff

​Discovery and management

​capabilities

​tags

​categories

Development workflow

Forking

save

test

chat

Publishing

Version history

diff

Discovery and management

capabilities

tags

categories