From e88f8836fe5c4f72ff8102fb6e04437921fe2c53 Mon Sep 17 00:00:00 2001 From: Vincent Grobler Date: Thu, 14 May 2026 18:31:41 +0100 Subject: [PATCH] docs: add CLI Tool page to Mintlify docs site - New docs/cli.md with full CLI guide (commands, config formats, MCP, teams, platform integration, CI/CD) - Added to mint.json navigation under Getting Started - Changelog updated with v1.10.0 CLI release entry --- docs/changelog.mdx | 20 +++ docs/cli.md | 362 +++++++++++++++++++++++++++++++++++++++++++++ docs/mint.json | 1 + 3 files changed, 383 insertions(+) create mode 100644 docs/cli.md diff --git a/docs/changelog.mdx b/docs/changelog.mdx index 5b043cc..5c103ee 100644 --- a/docs/changelog.mdx +++ b/docs/changelog.mdx @@ -9,6 +9,26 @@ All notable changes to CrewForm will be documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [1.10.0] — 2026-05-14 + +### Added + +- **CrewForm CLI (`npx crewform`)** — Standalone command-line tool for running AI agents locally without the web platform: + - **12 Commands** — `run`, `chat`, `init`, `validate`, `tools`, `login`, `logout`, `whoami`, `agents`, `teams`, `pull`, `push` + - **Local Agent Execution** — Run agents from JSON config files with streaming output, Ollama auto-detection, and 16 LLM provider support + - **Pipeline Teams** — Multi-agent pipeline execution with sequential steps, fan-out (parallel branches), merge agents, and configurable failure handling + - **MCP Client Integration** — Connect to MCP servers via `stdio`, `sse`, or `streamable-http` transports (`--mcp` flag) + - **Interactive Chat** — REPL with conversation history, token/cost tracking, and `/clear`, `/history`, `/stats`, `/exit` commands + - **Platform API Mode** — `crewform login` to authenticate, browse workspace agents/teams, `pull` configs locally, and `push` tasks remotely + - **Config Compatibility** — Accepts inline JSON and full `crewform-export` v1 format from the web app + - **Built-in Tools** — `web_search`, `http_request`, `code_interpreter`, `read_file`, `grammar_check` + - **Zero-Config Start** — `crewform init` scaffolds agent or team configs with Ollama model auto-detection + - **CI/CD Friendly** — `--json`, `--quiet`, stdin/stdout piping, and `CREWFORM_API_KEY` env var support + +### Documentation + +- New [CLI Tool](/cli) guide added to docs + ## [1.9.2] — 2026-05-08 ### Added diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..7b43b2a --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,362 @@ +--- +title: "CLI Tool" +description: "Run CrewForm agents from the command line — scriptable, CI/CD-friendly, Ollama-first." +icon: "terminal" +--- + +The CrewForm CLI (`npx crewform`) is a standalone command-line tool that lets you create, run, and manage AI agents locally — with optional connectivity to the CrewForm platform. + +## Installation + +```bash +# Use directly (zero install) +npx crewform + +# Or install globally +npm install -g crewform +``` + +## Quick Start + +```bash +# 1. Create an agent config +npx crewform init + +# 2. Run it (defaults to Ollama; set OPENAI_API_KEY for OpenAI, etc.) +npx crewform run agent.json "Summarise the latest AI news" + +# 3. Interactive chat +npx crewform chat agent.json +``` + +## Commands + +### Local Execution + +| Command | Description | +|---------|-------------| +| `crewform run [prompt]` | Run an agent or team from a JSON config | +| `crewform chat ` | Interactive chat session with an agent | +| `crewform init` | Create a starter agent or team config | +| `crewform validate ` | 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 ` | Download agent/team config to local JSON | +| `crewform push [prompt]` | Dispatch a task to a remote agent/team | + +## Running Agents + +### Basic Usage + +```bash +crewform run agent.json "Write a blog post about MCP" +``` + +### Input & Output + +```bash +# 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 +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 +# Create a team config +crewform init --team + +# Run it +crewform run team.json "Research and write about GraphQL best practices" +``` + +### Team Config Example + +```json +{ + "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 +{ + "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](/mcp-protocol) servers for dynamic tool discovery: + +```bash +crewform run agent.json --mcp mcp-servers.json "What tables are in my database?" +``` + +### MCP Server Config + +Create a `mcp-servers.json` file: + +```json +[ + { + "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 +# 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 +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 +# Download agent +crewform pull +crewform run my-agent.json "Hello" + +# Download team +crewform pull --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 +# Dispatch to an agent +crewform push "Write a quarterly report" + +# Dispatch to a team and wait for completion +crewform push --type team --wait "Research and summarise AI trends" + +# JSON output for CI/CD +crewform push "Generate report" --json +``` + +## Config Formats + +The CLI accepts three config formats: + + + + ```json + { + "name": "My Agent", + "model": "llama3.3", + "system_prompt": "You are a helpful assistant.", + "temperature": 0.7, + "tools": ["web_search"] + } + ``` + + + + Exported via **Agent → Menu → Export** in the dashboard: + ```json + { + "format": "crewform-export", + "version": 1, + "type": "agent", + "data": { + "name": "My Agent", + "model": "gpt-4o", + "system_prompt": "...", + "temperature": 0.7, + "tools": ["web_search"] + } + } + ``` + + + + 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 | — | +| `code_interpreter` | Run JavaScript code in a sandbox | — | +| `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 +# Install globally in CI +npm install -g crewform + +# 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 +``` diff --git a/docs/mint.json b/docs/mint.json index cdbfdee..4080481 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -48,6 +48,7 @@ "group": "Getting Started", "pages": [ "quickstart", + "cli", "self-hosting", "coolify-deployment", "troubleshooting"