npm package: @guildai/cli
Description: Guild.ai CLI - Build, test, and deploy AI agents
Author: Guild.ai
Latest version: 0.5.10

# Guild CLI

Command-line interface for [Guild.ai](https://guild.ai) — build, test, and deploy AI agents.

## Prerequisites

- **Node.js 18+** and **npm** — [nodejs.org](https://nodejs.org)
- **A Guild account** — Guild.ai is in closed beta. Request an invitation at hello@guild.ai

## Installation

```bash
npm install -g @guildai/cli
```

## Quick Start

### 1. Authenticate

```bash
guild auth login
```

This opens your browser to complete sign-in at [app.guild.ai](https://app.guild.ai). It also configures your local npm registry so the CLI can install Guild packages.

Verify:

```bash
guild auth status
```

### 2. Select a workspace

```bash
guild workspace select
```

If you have one workspace, it's selected automatically. If you have several, pick one from the list.

### 3. Create an agent

```bash
mkdir hello-agent && cd hello-agent
guild agent init --name hello-agent --template LLM
```

This creates the agent in the Guild backend, initializes a local git repo, and pulls starter files:

```
hello-agent/
├── agent.ts          # Your agent code
├── package.json      # Dependencies
├── tsconfig.json     # TypeScript config
├── guild.json        # Local config (managed by the CLI, don't edit)
└── .gitignore
```

### 4. Edit the agent

Open `agent.ts` and replace the contents:

```typescript
import { llmAgent, guildTools, userInterfaceTools } from '@guildai/agents-sdk';

export default llmAgent({
  description: 'A friendly greeting agent',
  tools: { ...guildTools, ...userInterfaceTools },
  systemPrompt: `You are a friendly assistant. Greet users warmly and answer their questions.`,
  mode: 'multi-turn',
});
```

### 5. Test it

```bash
guild agent test --ephemeral
```

Type a message and press Enter. Press `Ctrl+C` to exit.

### 6. Save and publish

```bash
guild agent save --message "First version" --wait --publish
```

- `--wait` blocks until validation passes
- `--publish` makes the agent available in the Guild catalog

## Templates

| Template             | Use when                                                             |
| -------------------- | -------------------------------------------------------------------- |
| `LLM`                | The LLM is 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.                      |

## Development Loop

The typical workflow: pull → edit → test → save.

```bash
guild agent pull                                    # Sync remote changes
# ... edit agent.ts ...
guild agent test                                    # Interactive test session
guild agent save --message "Add Slack notifications" # Save as draft
guild agent save --message "Ready" --wait --publish  # Save + validate + publish
```

## Commands

### Authentication

```bash
guild auth login                        # OAuth device flow login
guild auth logout                       # Remove stored token
guild auth status                       # Check authentication status
guild auth token                        # Print auth token to stdout (for scripting)
```

### Agents

```bash
guild agent init --name my-agent        # Initialize a new agent
guild agent clone <identifier>          # Clone an existing agent
guild agent pull                        # Pull remote changes
guild agent save --message "..."        # Save changes (creates draft version)
guild agent save --message "..." --wait --publish  # Save + validate + publish
guild agent publish                     # Publish latest draft version
guild agent unpublish                   # Unpublish latest published version
guild agent test                        # Interactive test session
guild agent test --ephemeral            # Test uncommitted changes
guild agent chat "Hello"               # Send a single message
guild agent get [identifier]            # Get agent details
guild agent versions [identifier]       # List version history
guild agent code [identifier]           # Fetch latest published code
guild agent list                        # List all agents
guild agent search <query>              # Search published agents
guild agent grep <pattern>              # Search agent code files
guild agent fork <agent-id>:<version>   # Fork an existing agent version
guild agent owners                      # List accounts that can own agents
guild agent tags list|add|remove        # Manage agent tags
guild agent revalidate                  # Re-run validation
```

### Workspaces

```bash
guild workspace list                    # List workspaces
guild workspace select                  # Select default workspace
guild workspace current                 # Show current workspace
guild workspace create <name>           # Create a new workspace
guild workspace get <identifier>        # Get workspace details
guild workspace agent list              # List agents in workspace
guild workspace agent add <agent-id>    # Add agent to workspace
guild workspace agent remove <agent-id> # Remove agent from workspace
guild workspace context list            # List context versions
guild workspace context get             # Get current context
guild workspace context edit            # Edit context (opens editor)
guild workspace context publish         # Publish draft context
```

### Sessions

```bash
guild session list                      # List sessions in a workspace
guild session get <session-id>          # Get session details
guild session events <session-id>       # List events in a session
guild session tasks <session-id>        # List tasks in a session
guild session create                    # Create a new session
guild session send <session-id>         # Send a message to a session
```

### Triggers

```bash
guild trigger list                      # List triggers in a workspace
guild trigger get <trigger-id>          # Get trigger details
guild trigger create                    # Create a new trigger
guild trigger update <trigger-id>       # Update a trigger
guild trigger activate <trigger-id>     # Activate a trigger
guild trigger deactivate <trigger-id>   # Deactivate a trigger
guild trigger sessions <trigger-id>     # List sessions spawned by a trigger
```

### Chat

```bash
guild chat                              # Interactive chat session
guild chat "your message"               # One-shot message
guild chat --agent <agent-id>           # Chat with specific agent
```

### Configuration

```bash
guild config list                       # Show all configuration values
guild config get <key>                  # Get a configuration value
guild config set <key> <value>          # Set a global configuration value
guild config path                       # Show configuration file paths
```

### Diagnostics

```bash
guild doctor                            # Check CLI setup and diagnose issues
guild version                           # Show version info
```

### Coding Assistant Skills

```bash
guild setup                             # Install skills + configure MCP server
guild setup --claude-md                 # Also create a CLAUDE.md template
guild setup --no-mcp                    # Install skills only, skip MCP configuration
guild mcp                               # Start MCP server (used by Claude Code, etc.)
```

### MCP Server

The CLI includes an [MCP](https://modelcontextprotocol.io/) server that exposes Guild's API to AI coding assistants like Claude Code.

**Setup:**

```bash
guild setup
```

This installs Claude Code skills and adds a `guild` entry to `.mcp.json` in your project. Claude Code (and other MCP-compatible tools) will automatically connect when they detect it.

**What it provides:**

- 24 tools: workspaces, agents, sessions, triggers, contexts, credentials
- 2 resources: current workspace info and installed agents
- All tools use your `guild auth` credentials automatically

**Manual start (for debugging):**

```bash
guild mcp
guild mcp --debug    # Verbose logging to stderr
```

## Configuration

**Global config** (`~/.guild/config.json`):

```json
{
  "default_workspace": "workspace-id"
}
```

**Local config** (`guild.json` in agent directory):

```json
{
  "agent_id": "agent-id",
  "workspace_id": "workspace-id"
}
```

### Token Storage

OAuth tokens are stored in your system's secure credential store:

- **macOS**: Keychain
- **Linux**: libsecret (GNOME Keyring, KWallet, etc.)
- **Windows**: Credential Manager

## Troubleshooting

### "Connection refused" or "Cannot connect to server"

1. Check your internet connection
2. Run `guild doctor` to see which check is failing

### "Not authenticated"

```bash
guild auth login
guild auth status
```

### "Workspace not found" or wrong workspace

```bash
guild workspace select
```

Or override for a single command:

```bash
GUILD_WORKSPACE_ID=<workspace-id> guild agent test
```

### "No agent ID provided and not in an agent directory"

Either run from inside an agent directory (one with a `guild.json` file), or pass the agent ID explicitly:

```bash
guild agent get <agent-id>
```

### "No changes to commit"

All changes are already committed. Make a code change first, then run `guild agent save` again.

### Validation failures

```bash
guild agent versions --limit 1          # Check for errors
# Fix the issue, then:
guild agent save --message "Fix" --wait
```

### Agent test not responding

1. Check your agent code compiles — look 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 instead: `guild agent chat "hello"`

### Keychain issues

- **macOS**: Ensure Keychain Access is working and not locked
- **Linux**: Install and configure libsecret (e.g., `gnome-keyring`)
- **Windows**: Check Credential Manager is accessible

### Command not found

Ensure npm global bin directory is in your PATH:

```bash
export PATH="$(npm config get prefix)/bin:$PATH"
```

## Support

- [Documentation](https://docs.guild.ai)
- [Guild.ai](https://guild.ai)

## License

Apache-2.0