guild agent - Guild

Build and manage agents. Each subcommand has its own section below, in alphabetical order. Most commands take an optional agent identifier: an agent ID or a full name such as myorg~my-agent. Leave it out to use the agent in guild.json in the current directory. A typical development loop looks like this:

guild agent init --name my-agent                  # Scaffold a new agent
guild agent chat                                  # Try it with an ephemeral build
guild agent test                                  # Run a test session
guild agent save --message "First version"        # Save a draft version
guild agent publish --wait                        # Validate and publish it

capabilities

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

guild agent capabilities                    # Tools for the current directory's agent
guild agent capabilities <identifier>       # Tools for a specific 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

Option	Description
`--version <id>`	The version to inspect. Defaults to the latest published version.
`--mode json`	Emit the raw payload, with `version_id`, `tools`, and `access` fields.

The command requires authentication, so 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 --mode json:

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

chat

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

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 jsonl                # Use JSONL input and output
guild agent chat --agent-version <id>        # Chat with a specific existing version
guild agent chat --no-cache                  # Force a fresh ephemeral build

Option	Description
`--agent-version <id>`	Chat with an existing version, given as a UUID or version number, instead of an ephemeral build.
`--mode <format>`	Input and output mode: `interactive` (default), `json`, or `jsonl`.
`--no-cache`	Skip the ephemeral build cache and force a fresh build.
`--no-splash`	Skip the splash screen animation.
`--open`	Open the session in the Guild web app.
`--path <dir>`	The agent directory. Defaults to the current directory.
`--resume <session-id>`	Resume an existing session. Works in every mode.
`--workspace <identifier>`	The workspace to run in, as an ID or full name such as `owner~workspace-name`.

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

Resuming a session skips version resolution and ephemeral builds, because the 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 session as a new user message. The CLI reports the session’s ID, and response polling only considers events created after your message. If the session doesn’t exist or you can’t 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

clone

Clone an agent’s repository into a local directory.

guild agent clone <identifier>
guild agent clone <identifier> --directory ./my-agent

Option	Description
`--directory <path>`	The directory to clone into.
`--force`	Clone even if the directory isn’t empty.

code

Fetch an agent’s latest code. By default, it prints the files as JSON and includes only published versions.

guild agent code <identifier>                    # Latest published code, as JSON
guild agent code <identifier> --draft            # Include draft versions
guild agent code <identifier> --output ./src     # Write the files to a directory

Option	Description
`--draft`	Include draft versions.
`--output <directory>`	Write the files to a directory instead of printing JSON.

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

Run it from inside an agent directory. The command needs a guild.json, and compares the Git-tracked files in your working tree, the same set test and chat upload.

fork

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

guild agent fork <identifier>                        # Fork the 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 it to an owner
guild agent fork <identifier> --directory ./my-fork  # Clone into a specific directory
guild agent fork <identifier> --category <name>      # Change the fork's category
guild agent fork <identifier> --tags a,b             # Set tags on the fork

Option	Description
`--category <name>`	The fork’s category. Defaults to the source agent’s category.
`--description <desc>`	A description for the fork.
`--directory <path>`	The directory to clone the fork into.
`--name <name>`	A name for the fork.
`--owner <owner>`	The owner, by name or ID.
`--tags <tags>`	Comma-separated tags for the fork.

A fork inherits the source agent’s category and its tags, except Guild’s own guild:-prefixed tags. Pass --category to change the category. The source tags are then dropped, and any --tags you pass are checked against the new category’s allowed tags. Run guild agent categories <category> to see them.

get

Show an agent’s details.

guild agent get                  # The agent in the current directory
guild agent get <identifier>     # A specific agent

grep

Search agent files for lines that match a pattern. The pattern is a JavaScript regular expression.

guild agent grep "task\.llm"                    # Search the current agent
guild agent grep "task\.llm" --all              # Search all agents you can see
guild agent grep "task\.llm" --all --published  # Search only published agents

Option	Description
`--all`	Search all agents, not just the current one.
`--published`	Search only published agents. Requires `--all`.

init

Initialize a new agent, in a new directory or the current one.

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 the owner by name or ID
guild agent init --name my-agent --category development --tags "code-review,testing"

Option	Description
`--agent-type <type>`	The agent type. See the table below.
`--category <name>`	The agent’s category. Run `guild agent categories` to list them.
`--directory <path>`	The directory to initialize. Defaults to `./<name>`, created if needed.
`--force`	Overwrite an existing `guild.json`.
`--fork <agent-id>`	Start from an existing agent.
`--name <name>`	The agent’s name.
`--owner <owner>`	The owner, by name or ID.
`--tags <tags>`	Comma-separated tags, from the category’s allowed tags.
`--template <template>`	`LLM` (default), `AUTO_MANAGED_STATE`, or `BLANK`.

Agent types are case-insensitive, and each one scaffolds a different entry point:

Agent type	Entry point
`GUILD_TYPESCRIPT`	`agent.ts`
`GUILD_NATIVE`	`PROMPT.md`
`GOOSE`	`recipe.yaml`
`OPENCLAW`	`AGENTS.md`
`LANGGRAPH`	`graph.py`

--agent-type appears only on accounts that have more than one agent type available. Omit it in a terminal and the CLI prompts you to choose. 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. Run guild config set default_owner <name-or-id> to set a default. In interactive mode, the CLI always prompts for the owner.

list

List agents. Without filters, it lists your own agents.

guild agent list                             # Your agents
guild agent list --owner myorg               # Agents owned by an organization
guild agent list --workspace <id>            # Agents installed in a workspace
guild agent list --search "code review"      # Filter by name or description
guild agent list --archived                  # Only archived agents

Option	Description
`--all`	Include archived agents.
`--archived`	Show only archived agents.
`--limit <n>`	Number of results to return (default: 20).
`--offset <n>`	Number of results to skip (default: 0).
`--owner <name>`	Filter by owner, as a user or organization name.
`--published`	Show only published agents. Ignored with `--workspace`.
`--search <query>`	Search by name or description.
`--sort <field>`	`name` (default), `updated`, `newest`, or `popular`.
`--workspace <id>`	List the agents installed in a workspace, by ID or name.

With --workspace, the list is the agents installed in that workspace, not the platform-wide roster. --published is ignored there, because installed agents already reference committed versions.

log

Show an agent’s version history as Git-log-style blocks. Each block shows 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 <identifier>                 # 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

Option	Description
`--limit <n>`	Maximum number of versions to return (default: 20).
`--offset <n>`	Number of versions to skip (default: 0).

For build and validation output, use logs.

logs

Show the build and validation step logs for an agent version.

guild agent logs                              # Logs for the latest version
guild agent logs <identifier> <version-id>    # Logs for a specific version

For the version history, use log. For options and output format, see guild agent logs.

owners

List the accounts that can own an agent. Pass one of them to --owner on init or fork.

guild agent owners

publish

Publish the latest draft version of an agent.

guild agent publish                           # Publish the latest draft
guild agent publish <identifier>              # Publish a specific agent's latest draft
guild agent publish --wait                    # Wait for validation before publishing
guild agent publish --wait --timeout 600      # Wait up to 600 seconds

Option	Description
`--timeout <seconds>`	Seconds to wait for validation and publishing with `--wait` (default: 300). Must be a positive integer.
`--wait`	Wait for validation to finish before publishing.

To save and publish in one step, use save --publish. To take a version back down, use unpublish.

pull

Pull the latest saved agent files into the current directory, without using Git.

guild agent pull
guild agent pull --force     # Replace conflicting local files with the remote version

Option	Description
`--force`	Replace conflicting local files with the remote version.

revalidate

Run validation again on an agent version. It uses the latest version unless you pass a version ID.

guild agent revalidate                             # The latest version of the current agent
guild agent revalidate <identifier> <version-id>   # A specific version

save

Upload the agent’s files and create a new version. The target must already exist unless you pass --create-if-missing. Versions start as drafts until you publish them. save sends the files through the Guild API; it doesn’t commit or push with Git.

guild agent save --message "Add rate limiting"
guild agent save --message "Fix bug" --wait                          # Wait for validation
guild agent save --message "Ship it" --publish                       # Save and publish
guild agent save --message "Breaking change" --publish --bump major  # Bump the major version
guild agent save --message "Pin release" --version-number 2.1.0      # Set the version explicitly
guild agent save myorg~my-agent --path ./agents/my-agent --message "Release" --publish  # Save from any directory

Argument	Description
`[agent]`	The target agent, as a UUID or full name such as `myorg~my-agent`. Creating a missing target requires a full name. Short names are rejected. Leave it out to use `guild.json` in the source directory.

Option	Description
`--bump [level]`	Bump the `package.json` version before saving: `patch` (default), `minor`, or `major`.
`--create-if-missing`	Create a missing `owner~name` as a private agent. Requires `--agent-type`. Available in CLI 0.27.1 and later.
`--agent-type <type>`	Required with `--create-if-missing`: `GUILD_NATIVE`, `GUILD_TYPESCRIPT`, `GOOSE`, `OPENCLAW`, or `LANGGRAPH`, subject to the account’s enabled types. Must match an existing target’s type.
`--force`	Save even when the agent’s latest version differs from your last save, or when a fresh directory’s files differ from the agent’s source.
`-m, --message <text>`	A summary of this version.
`--no-bump`	Skip the automatic version bump.
`--path <directory>`	The source directory. Defaults to the current directory. Ignore rules, version bumps, and saved state all use this directory.
`--publish`	Publish after validation passes. Implies `--wait`.
`--timeout <seconds>`	Seconds to wait for validation and publishing (default: 300). Must be a positive integer.
`--version-number <version>`	Set the version explicitly, overriding the `package.json` version.
`--wait`	Wait for validation to finish before returning.

--publish always waits for validation and publishing to finish, then prints Version is now published and available in the catalog. If --timeout isn’t a positive integer, 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:

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

Which files are saved

save uploads every file in the source directory except:

Files matched by .gitignore. In CLI 0.27.2 and later, rules apply from the repository root through the selected directory and its nested directories, including negation. Outside a Git repository, rules start at the selected directory.
.git, .guild, node_modules, dist, .env and .env*, guild.json, .npmrc, .DS_Store, and Thumbs.db, which are never uploaded.

A negation rule can’t bring back an always-excluded file. Global Git excludes and .git/info/exclude don’t apply, and it doesn’t matter whether Git tracks a file. Parent .gitignore files contribute rules, but they aren’t uploaded with a nested agent. Each save is a full snapshot: a file that exists in Guild but not in your directory is removed from the new version. Files must be valid UTF-8. -A/--all is deprecated and ignored. After each save, the CLI records the version and a hash of each file in .guild/state.json. If nothing changed since that save, save says so instead of creating a version. If the agent has a newer version than your last save, save stops unless you pass --force.

Save from your own repository

To save or publish from your own machine, sign in with guild auth login. You don’t need an API key. If GUILD_API_KEY is set, it takes precedence over your login, so unset it first. You don’t need guild agent clone or a guild.json to save. Name the existing agent and point --path at its source:

guild agent save myorg~my-agent --path ./agents/my-agent --message "Release" --publish

The named agent takes precedence over any guild.json in the directory, without changing it. The first save from a fresh directory compares its files with the agent’s latest version and asks you to confirm before replacing them, or you can pass --force. The same command works with an account API key. Set GUILD_API_KEY to a key with the agents:write scope, which lets a CI pipeline publish versions without guild auth login:

GUILD_API_KEY="<api_key_id>:<api_key_secret>" \
  guild agent save myorg~my-agent --path ./agents/my-agent \
  --no-bump --force --message "Release" --publish

To create a missing agent during its first release, use CLI 0.27.1 or later and opt in explicitly:

guild agent save myorg~my-agent --path ./agents/my-agent \
  --create-if-missing --agent-type GOOSE --version-number 1.0.0 --publish

The CLI creates the agent only when the target doesn’t exist. An authentication or permission error never triggers creation. The new agent is private, and publishing doesn’t change its visibility. If validation fails, the unpublished agent stays in place for you to inspect. You can also create the agent first with init. For a reusable workflow, see Publish from GitHub Actions. TypeScript agents take their version from package.json. Goose and Guild Native agents have no package.json, so save skips the version-bump checks for them, and --bump does nothing. When you run save --publish on one of them without --version-number, the CLI uses the next patch version after the latest published one, or 1.0.0 if none is published. For TypeScript agents, save also checks package-lock.json to keep dependency installs reproducible. The lockfile must be tracked in Git and in sync with package.json. If it’s stale or invalid, the save stops so you can run npm install and commit the result. If it’s missing, untracked, or ignored, the CLI warns you and falls back to legacy dependency resolution.

search

Search agents by name and description.

guild agent search "code review"
guild agent search "code review" --published --sort popular

Option	Description
`--limit <n>`	Number of results to return (default: 20).
`--offset <n>`	Number of results to skip (default: 0).
`--published`	Show only published agents.
`--sort <field>`	`updated` (default), `newest`, `name`, or `popular`.

test

Test the agent in the current directory. guild agent test polls for the agent’s response and prints it.

guild agent test                             # Test the current directory's agent
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
guild agent test --bundle agent.js.gz --agent my-agent  # Test a pre-built bundle against an existing agent

Option	Description
`--agent <id-or-name>`	The agent to test a `--bundle` against.
`--agent-version <id>`	Test an existing version, given as a UUID or version number.
`--bundle <file>`	Test a pre-built bundle file instead of building from the current directory. Requires `--agent`.
`--events <types>`	Event types to show (default: `user`). See Event filtering.
`--mode <format>`	Output format: `interactive` (default), `json`, or `jsonl`.
`--no-cache`	Skip the ephemeral build cache and force a fresh build.
`--open`	Open the session in the Guild web app.
`--resume <session-id>`	Resume an existing session, such as one whose response poll timed out.
`--timeout <seconds>`	Seconds to wait 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>`.
`--workspace <identifier>`	The workspace to run in, as an ID or full name.

A poll timeout is recoverable: the session isn’t discarded, so you can resume it. In --mode json, the error output includes the session ID and the hint guild agent test --resume <session-id>. In --mode jsonl, the timeout output includes the same, and the command continues to the next input line. Pass --bundle <file> with --agent <id-or-name> to test a pre-built bundle without cloning the agent first. This mode needs no guild.json and uploads only the bundle you name. It works with GUILD_API_KEY set in CI, so you can test a bundle straight from a pipeline.

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 the agent’s type needs are present: agent.ts and package.json for Guild TypeScript, PROMPT.md for Guild Native, recipe.yaml for Goose, AGENTS.md for OpenClaw, and langgraph.json for LangGraph. It resolves the type from guild.json or the Guild API, and names the missing file.

unarchive

Restore an archived agent.

guild agent unarchive                 # The agent in the current directory
guild agent unarchive <identifier>    # A specific agent

unpublish

Unpublish an agent’s latest published version.

guild agent unpublish
guild agent unpublish <identifier>

update

Change an agent’s visibility.

guild agent update <identifier> --public     # Visible to everyone
guild agent update <identifier> --private    # Visible only to the owner

Option	Description
`--private`	Make the agent visible only to its owner.
`--public`	Make the agent visible to everyone.
`--yes`	Skip the confirmation prompt.

versions

List an agent’s versions.

guild agent versions
guild agent versions <identifier> --limit 50

Option	Description
`--limit <n>`	Maximum number of versions to return (default: 20).
`--offset <n>`	Number of versions to skip (default: 0).

For a Git-log-style view with commit SHAs and summaries, use log.

workspaces

List the workspaces that use an agent.

guild agent workspaces
guild agent workspaces <identifier> --limit 50

Option	Description
`--limit <n>`	Maximum number of workspaces to return (default: 20).
`--offset <n>`	Number of workspaces to skip (default: 0).

​archive

​capabilities

​categories

​chat

​clone

​code

​diff

​fork

​get

​grep

​init

​list

​log

​logs

​owners

​publish

​pull

​revalidate

​save

​Which files are saved

​Save from your own repository

​search

​tags

​test

​unarchive

​unpublish

​update

​versions

​workspaces

archive

capabilities

categories

chat

clone

code

diff

fork

get

grep

init

list

log

logs

owners

publish

pull

revalidate

save

Which files are saved

Save from your own repository

search

tags

test

unarchive

unpublish

update

versions

workspaces