> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewform.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Tool

> Run CrewForm agents from the command line — scriptable, CI/CD-friendly, Ollama-first.

The CrewForm CLI (`npx @crewformhq/cli`) is a standalone command-line tool that lets you create, run, and manage AI agents locally — with optional connectivity to the CrewForm platform.

## Installation

CLI 0.3.0 uses MIT and includes the offline walkthrough, diagnostics and named
device profiles. The original 0.2.0 npm artifact retains its original licence.

```bash theme={null}
# Use directly (zero install)
npx @crewformhq/cli@0.3.0

# Or install globally
npm install -g @crewformhq/cli@0.3.0
```

## Quick Start

```bash theme={null}
# 1. Create an agent config
npx @crewformhq/cli init

# 2. Run it (defaults to Ollama; set OPENAI_API_KEY for OpenAI, etc.)
npx @crewformhq/cli run agent.json "Summarise the latest AI news"

# 3. Interactive chat
npx @crewformhq/cli chat agent.json
```

## Commands

### Offline walkthrough and diagnostics

Use the published package directly:

```bash theme={null}
npx @crewformhq/cli@0.3.0 demo --output review-pack.json
npx @crewformhq/cli@0.3.0 doctor --runtime codex:cli --json
```

Alternatively, build from a checkout with `npm --prefix cli ci && npm --prefix cli run build`, then run:

```bash theme={null}
node cli/dist/cli.js demo --output review-pack.json
node cli/dist/cli.js doctor --runtime codex:cli --json
```

`demo` runs the real sequential pipeline with scripted outputs. It needs no account,
backend, provider key, installed agent or network access. The JSON pack is marked
`simulated: true` and `humanReview: required`; it is not an AI evaluation.
`doctor` probes executable versions only. A successful check does not prove login,
subscription eligibility, ACP compatibility or model availability.

### Local Execution

| Command | Description |
| - | - |
| `crewform run <file> [prompt]` | Run an agent or team from a JSON config |
| `crewform chat <file>` | Interactive chat session with an agent |
| `crewform init` | Create a starter agent or team config |
| `crewform validate <file>` | Validate a config file |
| `crewform tools` | List available built-in tools |

### Platform (API-Connected)

| Command | Description |
| - | - |
| `crewform login` | Authenticate with your CrewForm API key |
| `crewform logout` | Remove saved credentials |
| `crewform whoami` | Show authenticated user & workspace |
| `crewform agents` | List agents in your workspace |
| `crewform teams` | List teams in your workspace |
| `crewform pull <id>` | Download agent/team config to local JSON |
| `crewform push <id> [prompt]` | Dispatch a task to a remote agent/team |

## Running Agents

### Basic Usage

```bash theme={null}
crewform run agent.json "Write a blog post about MCP"
```

### Input & Output

```bash theme={null}
# Read prompt from a file
crewform run agent.json --input prompt.txt

# Save output to a file
crewform run agent.json "Generate a report" --output report.md

# Pipe input/output (CI/CD friendly)
echo "Review this code" | crewform run agent.json
crewform run agent.json "Summarise" > summary.txt

# JSON output with token usage and metadata
crewform run agent.json "Hello" --json

# Quiet mode (suppress streaming, show only final result)
crewform run agent.json "Hello" --quiet
```

## Interactive Chat

Start a REPL session with conversation history:

```bash theme={null}
crewform chat agent.json
```

**In-chat commands:**

| Command | Action |
| - | - |
| `/clear` | Clear conversation history |
| `/history` | Show recent messages |
| `/stats` | Show token usage & cost estimate |
| `/exit` | End session |

## Pipeline Teams

Run multi-agent workflows locally. Agents execute in sequence, with each step's output passed as context to the next.

```bash theme={null}
# Create a team config
crewform init --team

# Run it
crewform run team.json "Research and write about GraphQL best practices"
```

### Team Config Example

```json theme={null}
{
  "name": "Research & Write Team",
  "mode": "pipeline",
  "agents": [
    {
      "ref_id": "researcher",
      "role": "researcher",
      "agent": {
        "name": "Researcher",
        "model": "gpt-4o",
        "system_prompt": "You are a thorough research agent...",
        "temperature": 0.3,
        "tools": ["web_search"]
      }
    },
    {
      "ref_id": "writer",
      "role": "writer",
      "agent": {
        "name": "Writer",
        "model": "gpt-4o",
        "system_prompt": "You are an expert technical writer...",
        "temperature": 0.7,
        "tools": []
      }
    }
  ],
  "config": {
    "steps": [
      {
        "step_name": "Research",
        "agent_ref": "researcher",
        "instructions": "Research the given topic thoroughly",
        "expected_output": "Comprehensive research notes with sources",
        "on_failure": "stop",
        "max_retries": 1
      },
      {
        "step_name": "Write",
        "agent_ref": "writer",
        "instructions": "Write a polished article from the research",
        "expected_output": "A well-structured blog post",
        "on_failure": "stop",
        "max_retries": 0
      }
    ]
  }
}
```

### Fan-Out (Parallel Execution)

Steps with `type: "fan_out"` run multiple agents in parallel, then merge results:

```json theme={null}
{
  "step_name": "Parallel Research",
  "type": "fan_out",
  "parallel_agents": ["researcher-1", "researcher-2", "researcher-3"],
  "merge_agent_ref": "synthesiser",
  "merge_instructions": "Combine all research into a single report",
  "fan_out_failure": "continue_on_partial"
}
```

**Failure modes:**

* `fail_fast` — Stop all branches if any fails
* `continue_on_partial` — Collect results from successful branches

## MCP Server Integration

Connect agents to external [MCP](https://docs.crewform.tech/mcp-protocol.md) servers for dynamic tool discovery:

```bash theme={null}
crewform run agent.json --mcp mcp-servers.json "What tables are in my database?"
```

### MCP Server Config

Create a `mcp-servers.json` file:

```json theme={null}
[
  {
    "name": "postgres",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
  },
  {
    "name": "filesystem",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
  },
  {
    "name": "remote-tools",
    "transport": "streamable-http",
    "url": "https://mcp.example.com/sse"
  }
]
```

**Supported transports:** `stdio`, `sse`, `streamable-http`

## Platform Integration

Connect the CLI to your CrewForm workspace to browse, download, and dispatch agents remotely.

### Authenticate

Get your API key from **Settings → API Keys** in the [CrewForm dashboard](https://app.crewform.tech).

```bash theme={null}
# Interactive — prompts for your API key
crewform login

# Non-interactive (CI/CD)
crewform login --api-key cf_sk_abc123

# Self-hosted instance
crewform login --api-key cf_sk_abc123 --api-url https://my-instance.example.com
```

Credentials are saved to `~/.crewform/config.json`.

### Browse Your Workspace

```bash theme={null}
crewform whoami      # Show user, workspace, plan
crewform agents      # List agents (name, model, ID)
crewform teams       # List teams (mode, member count, ID)

# JSON output for scripting
crewform agents --json | jq '.items[].name'
```

### Download Agents Locally

Pull an agent or team from the platform and run it locally:

```bash theme={null}
# Download agent
crewform pull <agent-uuid>
crewform run my-agent.json "Hello"

# Download team
crewform pull <team-uuid> --type team
crewform run my-pipeline.json "Research AI trends"
```

### Dispatch Work Remotely

Send a task to a cloud-hosted agent or team without running locally:

```bash theme={null}
# Dispatch to an agent
crewform push <agent-uuid> "Write a quarterly report"

# Dispatch to a team and wait for completion
crewform push <team-uuid> --type team --wait "Research and summarise AI trends"

# JSON output for CI/CD
crewform push <agent-uuid> "Generate report" --json
```

## Config Formats

The CLI accepts three config formats:

> [accordion] Inline Agent (simplest)
>
> ```json theme={null}
> {
>   "name": "My Agent",
>   "model": "llama3.3",
>   "system_prompt": "You are a helpful assistant.",
>   "temperature": 0.7,
>   "tools": ["web_search"]
> }
> ```

> [accordion] CrewForm Export (from the web app)
>
> Exported via **Agent → Menu → Export** in the dashboard:
>
> ```json theme={null}
> {
>   "format": "crewform-export",
>   "version": 1,
>   "type": "agent",
>   "data": {
>     "name": "My Agent",
>     "model": "gpt-4o",
>     "system_prompt": "...",
>     "temperature": 0.7,
>     "tools": ["web_search"]
>   }
> }
> ```

> [accordion] Team Config
>
> See the [Pipeline Teams](#pipeline-teams) section above for the full team config format.

## Built-in Tools

| Tool | Description | Requires |
| - | - | - |
| `web_search` | Search the web via Serper API | `SERPER_API_KEY` |
| `http_request` | Make HTTP GET/POST requests | — |
| `read_file` | Read a file from a URL | — |
| `grammar_check` | Check grammar and spelling | — |

Plus any tools discovered from connected MCP servers.

## Environment Variables

| Variable | Purpose |
| - | - |
| `CREWFORM_API_KEY` | API key for platform commands (alternative to `crewform login`) |
| `CREWFORM_API_URL` | Custom API URL for self-hosted instances |
| `SERPER_API_KEY` | Required for `web_search` tool |
| `OPENAI_API_KEY` | OpenAI provider |
| `ANTHROPIC_API_KEY` | Anthropic provider |
| `GOOGLE_API_KEY` | Google Gemini provider |

See the [CLI README](https://github.com/CrewForm/crewform/blob/main/cli/README.md) for the full list of supported providers and their environment variables.

## CI/CD Integration

The CLI is designed for automation:

```bash theme={null}
# Install globally in CI
npm install -g @crewformhq/cli

# Run with JSON output for parsing
OPENAI_API_KEY=${{ secrets.OPENAI_KEY }} \
  crewform run agent.json "Review this PR" --json > review.json

# Dispatch to cloud and wait
CREWFORM_API_KEY=${{ secrets.CREWFORM_KEY }} \
  crewform push $AGENT_ID --wait --json "Generate release notes" > notes.json
```

The legacy `code_interpreter` tool is disabled: model-generated JavaScript must not execute inside the CLI process. Use a separately isolated execution service for code tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.