> ## 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.
# CLI reference
> Install the Guild CLI and learn the agent development workflow.
The Guild CLI is your primary tool for creating, testing, and publishing agents locally.
## Installation
### Prerequisites
* **Node.js 18+** and **npm** — [nodejs.org](https://nodejs.org)
* **A Guild account** — your Guild contact provides access
### Install and authenticate
```bash theme={null}
# Install the CLI
npm i @guildai/cli -g
# Authenticate with Guild
guild auth login
# Verify
guild auth status
```
`guild auth login` opens your browser to sign in at [app.guild.ai](https://app.guild.ai) and configures your local npm registry for Guild packages.
### Coding assistant skills
If you use Claude Code, install Guild CLI skills into your project:
```bash theme={null}
guild setup
```
This adds SDK reference and CLI workflow docs to `.claude/skills/` so your coding assistant understands Guild agent development patterns.
## Create an agent
```bash theme={null}
mkdir my-agent && cd my-agent
guild agent init
```
The CLI prompts for a name, template, and category. Every agent requires a category, and any tags you provide are validated against that category's allowed tags. Skip prompts with flags:
```bash theme={null}
guild agent init --name my-agent --template LLM --category development
```
### Templates
| Template | Use when |
| -------------------- | ---------------------------------------------------------------------------- |
| `LLM` | The LLM drives the logic. You write a prompt and pick tools. **Start here.** |
| `AUTO_MANAGED_STATE` | You write procedural TypeScript that calls tools inline. |
| `BLANK` | You want full control over the agent lifecycle. |
### Project structure
```text theme={null}
my-agent/
├── agent.ts # Your agent code (edit this)
├── package.json # Dependencies (runtime packages pre-configured)
├── tsconfig.json # TypeScript config
├── guild.json # Local config (managed by CLI, don't edit)
└── .gitignore
```
### Guild Native agents
When you initialize a Guild Native agent, the scaffold includes:
```text theme={null}
my-agent/
├── PROMPT.md # Agent role, behavior, and instructions
├── DESCRIPTION.md # Brief description of the agent
├── README.md
└── .gitignore
```
* **`PROMPT.md`** — defines the agent's role, behavior, and instructions.
* **`DESCRIPTION.md`** — provides a brief description of what the agent does.
Guild Native agents skip the build validation step and immediately transition to `READY` after initialization.
### Goose agents
When you initialize a Goose agent, the scaffold includes:
```text theme={null}
my-agent/
├── recipe.yaml # Agent parameters, instructions, and response JSON schema
├── README.md
└── .gitignore
```
* **`recipe.yaml`** — defines the agent's parameters, instructions, and response JSON schema.
Goose agents skip the build validation step and immediately transition to `READY` after initialization.
## Write your agent
Edit `agent.ts`. The template gives you a working starting point.
### LLM agent
Define a system prompt and tools. No procedural code needed.
```typescript theme={null}
import { llmAgent, guildTools } from "@guildai/agents-sdk"
import { gitHubTools } from "@guildai-services/guildai~github"
export default llmAgent({
description: "Answers questions about GitHub repositories",
tools: { ...gitHubTools, ...guildTools },
systemPrompt: `You help users understand their GitHub repositories.
Use the GitHub tools to look up real data when asked.`,
mode: "multi-turn",
})
```
`mode: "multi-turn"` keeps the conversation going after each response. Use `"one-shot"` (default) when the agent should respond once and finish.
`llmAgent` wires `ui_notify` internally so progress notifications (`task.ui.notify()`) work, but hides it from the model unless you explicitly add `ui_notify` to your agent's `tools`. Add `userInterfaceTools` if your agent needs `ui_prompt` or `ui_ping`.
### Code-first agent
Write TypeScript that calls tools directly. Requires the `"use agent"` directive at the top of the file so the runtime can manage state between tool calls.
```typescript theme={null}
"use agent"
import { agent, guildTools, type Task } from "@guildai/agents-sdk"
import { gitHubTools } from "@guildai-services/guildai~github"
import { z } from "zod"
const tools = { ...gitHubTools, ...guildTools }
type Tools = typeof tools
const inputSchema = z.object({
type: z.literal("text"),
text: z.string().describe("Repository in owner/repo format"),
})
const outputSchema = z.object({
type: z.literal("text"),
text: z.string(),
})
async function run(input: z.infer, task: Task) {
const prs = await task.tools.github_search_issues_and_pull_requests({
q: `is:pr is:open repo:${input.text}`,
per_page: 10,
})
if (!prs.items?.length) {
return { type: "text" as const, text: "No open PRs." }
}
const summary = prs.items
.map((pr) => `- #${pr.number}: ${pr.title}`)
.join("\n")
return { type: "text" as const, text: summary }
}
export default agent({
description: "Lists open PRs in a GitHub repo",
inputSchema,
outputSchema,
tools,
run,
})
```
### Tools overview
Agents have access to three categories of tools:
* **Service tools** (`gitHubTools`, etc.) — call third-party APIs. When a user first triggers a service tool, Guild prompts them to connect their account via OAuth.
* **`guildTools`** — query the Guild platform (agents, workspaces, sessions, triggers).
* **`userInterfaceTools`** — interact with the user during a session (questions, progress updates).
All tool calls go through `task.tools`:
```typescript theme={null}
const pr = await task.tools.github_pulls_get({ owner, repo, pull_number: 42 })
await task.tools.slack_chat_post_message({ channel: "C123", text: "PR merged" })
const answer = await task.tools.ui_prompt({ type: "text", text: "Which repo?" })
```
## Available services
The runtime provides 7 service integrations (GitHub, Slack, Azure DevOps, Confluence, and more). Import them from their `@guildai-services/*` packages -- don't add them to `package.json`.
See [Service integrations](/sdk/tools#service-integrations) for the full list with import paths.
Credentials for each service are configured at the organization level in **Settings > Credentials** at [app.guild.ai](https://app.guild.ai). When an agent first uses a service tool, Guild prompts the user to connect if credentials aren't already configured.
## Development loop
The typical workflow: **pull, edit, test, save**.
### Pull latest changes
If others are working on the same agent:
```bash theme={null}
guild agent pull
```
### Test locally
```bash theme={null}
guild agent test # Interactive chat session
guild agent chat "Hello" # Send a single message
```
`guild agent test` opens an interactive session. Ephemeral versions are created automatically when testing from a local agent directory. Changes to `agent.ts` take effect on the next save — no restart needed.
`guild agent test` includes only files tracked by Git. Files that are already committed or staged with `git add` are uploaded to the ephemeral version. 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.
### Chat with a published agent
To chat with a published agent by name, use `guild workspace chat --agent` from any directory:
```bash theme={null}
guild workspace chat --agent owner~agent-name
guild workspace chat --agent owner~agent-name --workspace owner~workspace-name
guild workspace chat --agent owner~agent-name --once "What can you do?"
```
`guild chat` opens [The Smith](/platform/smith), Guild's built-in support agent. To chat with the generic workspace assistant or a specific agent, use `guild workspace chat`.
### Save your work
```bash theme={null}
guild agent save --message "Add Slack notifications"
```
This commits your code and creates a new version in the Guild backend. Versions start as drafts.
`guild agent save -A/--all` commits only modified tracked files. New files are untracked, so stage them with `git add ` (or `git add .`) before you run `save -A`.
### Publish
```bash theme={null}
guild agent save --message "Ready to ship" --wait --publish
```
`--wait` blocks until validation passes. `--publish` makes the agent available to your organization.
Publish separately if needed:
```bash theme={null}
guild agent publish
```
### Check status
```bash theme={null}
guild agent get # Agent info and current version
guild agent versions # Version history
guild agent code # View source of latest version
```
## Key rules
* Agent code lives at `agent.ts` in the project root.
* Don't add `@guildai/agents-sdk`, `zod`, or `@guildai-services/*` to `package.json` — the runtime provides them.
* Call tools through `task.tools.(args)`. Never access services directly.
* Use `guild agent save` to commit and `guild agent pull` to sync. Don't use raw git commands.
* Don't edit `guild.json` — it's managed by the CLI.
## Commands
### Agent commands
```bash theme={null}
guild agent init # Create a new agent
guild agent init --fork owner~agent-name # Fork an existing agent
guild agent categories # List categories and their allowed tags
guild agent clone owner~agent-name # Clone an agent to work on locally
guild agent pull # Pull remote changes
guild agent save --message "..." # Commit and upload
guild agent publish # Publish to your organization
guild agent unpublish # Unpublish from your organization
guild agent revalidate # Re-run validation
guild agent get # Agent info
guild agent versions # Version history
guild agent code # View latest source
guild agent capabilities # Show resolved tools
guild agent test # Interactive test session
guild agent chat "message" # Send a single message
```
### Chat
```bash theme={null}
guild workspace chat --agent owner~agent-name # Chat with a published agent by name
guild workspace chat --agent owner~agent-name --once "message" # One-shot mode
```
### Other commands
```bash theme={null}
guild auth login # Authenticate with Guild
guild auth logout # Sign out
guild auth status # Check authentication
guild workspace select # Set default workspace
guild doctor # Check CLI setup
guild setup # Install coding assistant skills
```
## Diagnostics
Run `guild doctor` to check your setup:
```bash theme={null}
guild doctor
```
```text theme={null}
Checking Guild CLI setup...
✓ Authentication Logged in
✓ Server Connected to https://app.guild.ai/api (125ms)
✓ Global config ~/.guild/config.json
✓ Default workspace my-workspace
- Local config Not in an agent directory
✓ Git Installed
5 passed, 0 failed, 1 skipped
```
## Troubleshooting
1. Check your internet connection.
2. Run `guild doctor` to identify which check is failing.
Your default workspace may not match the target. Override with an environment variable:
```bash theme={null}
GUILD_WORKSPACE_ID= guild agent chat "hello"
```
Or set a new default:
```bash theme={null}
guild workspace select
```
Re-authenticate:
```bash theme={null}
guild auth login
guild auth status
```
Run from inside an agent directory (one with a `guild.json` file), or pass the agent ID explicitly:
```bash theme={null}
guild agent get
```
If a previous save committed locally but failed to push, run save again — it detects unpushed commits and resumes:
```bash theme={null}
guild agent save --message "Retry"
```
`guild agent save -A/--all` commits only modified tracked files, so a newly created file is untracked and is skipped. Stage it first, then save:
```bash theme={null}
git add path/to/new-file
guild agent save -A --message "Add new file"
```
Check the latest version for errors and save again:
```bash theme={null}
guild agent versions --limit 1
guild agent save --message "Fix validation error" --wait
```
1. Check for TypeScript errors in `agent.ts`.
2. Make sure you've saved at least once: `guild agent save --message "initial"`.
3. Try a single message: `guild agent chat "hello"`.