CLI reference

# Install the CLI
npm i @guildai/cli -g

# Authenticate with Guild
guild auth login

# Verify
guild auth status

guild setup

guild agent init

guild agent init --name my-agent --template LLM --category development

my-agent/
├── agent.ts          # Your agent code (edit this)
├── markdown.d.ts     # Lets the agent import Markdown files as strings
├── package.json      # Dependencies (runtime packages pre-configured)
├── tsconfig.json     # TypeScript config
├── guild.json        # Local config (managed by CLI, don't edit)
├── README.md
└── .gitignore

my-agent/
├── PROMPT.md         # Agent role, behavior, and instructions
├── guild.yaml        # Integrations, sub-agents, and built-in tools
├── README.md
└── .gitignore

my-agent/
├── recipe.yaml       # Agent parameters, instructions, and response JSON schema
├── guild.yaml        # Integrations, sub-agents, and built-in tools
├── README.md
└── .gitignore

my-agent/
├── AGENTS.md         # The agent's instructions — becomes the system prompt
├── guild.yaml        # Integrations, sub-agents, and built-in tools
├── README.md
└── .gitignore

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",
})

"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<typeof inputSchema>, task: Task<Tools>) {
  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,
})

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?" })

guild agent pull

guild agent test              # Interactive chat session
guild agent chat "Hello"      # Send a single message

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 agent save --message "Add Slack notifications"

guild agent save --message "Ready to ship" --wait --publish

guild agent publish

guild agent get                # Agent info and current version
guild agent versions           # Version history
guild agent code               # View source of latest version

guild agent init                          # Create a new agent
guild agent init --owner <name-or-id>     # Specify owner (required in CI/scripted use with orgs)
guild agent init --fork owner~agent-name  # Fork an existing agent
guild agent categories                    # List all categories
guild agent categories <name>             # Show a category and its 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 log                           # Version history as git-log-style blocks
guild agent diff                          # Diff local files against the latest published version
guild agent logs                          # Build/validation step logs
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

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

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

guild doctor

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