Complete reference for the Flutch command-line interface.

Installation

Install Flutch CLI globally via npm:

bash
npm install -g flutch

Requirements:

Node.js 18+
Python 3.9+ (for Python agents)

Verify Installation

bash
flutch --version
# Output: flutch v1.0.0

Update CLI

bash
npm update -g flutch

Or install specific version:

bash
npm install -g [email protected]

Global Commands

flutch --help

Get general help or command-specific help.

bash
# General help
flutch --help
flutch -h

# Command-specific help
flutch graph --help
flutch graph deploy --help

flutch --version

Show CLI version.

bash
flutch --version
flutch -v

Output:

flutch v1.0.0

Authentication Commands

flutch whoami

Check current authentication status.

bash
flutch whoami

Output:

Logged in as: [email protected]
Company: acme-corp
API Endpoint: https://api.flutch.ai

flutch config

Manage CLI configuration.

bash
# View current config
flutch config

# Set configuration values
flutch config set <key> <value>

# Get specific value
flutch config get <key>

Examples:

bash
# Set API endpoint
flutch config set apiEndpoint https://api.flutch.ai

# View API key
flutch config get apiKey

Graph Commands

All graph commands use the flutch graph prefix.

flutch graph create

Create a new graph project from template.

bash
flutch graph create <project-name>

Interactive wizard asks:

Language (Python or TypeScript)
Framework (LangGraph, LlamaIndex Workflows, Haystack Pipelines)
Template (Simple starter or advanced example)

Examples:

bash
# Interactive mode
flutch graph create my-agent

# Specify language
flutch graph create my-agent --language python
flutch graph create my-agent --language typescript

# Specify framework
flutch graph create my-agent --framework langgraph

# Complete non-interactive
flutch graph create my-agent --language python --framework langgraph --template simple

Options:

Option	Values	Description
`--language`	`python`, `typescript`	Project language
`--framework`	`langgraph`, `llamaindex`, `haystack`	Workflow framework
`--template`	`simple`, `advanced`	Starting template
`--path`	`<directory>`	Custom output directory

Output:

Creating project 'my-agent'...
Generating project structure...
Project created successfully!

Next steps:
  cd my-agent
  npm install  # or pip install -r requirements.txt
  flutch graph register

flutch graph validate

Validate graph manifest and configuration.

bash
flutch graph validate

Checks:

Manifest syntax and required fields
Version format (semver)
Version consistency
File structure
Config schema validity

Output:

Validating manifest...                    ✓
Checking version format...                ✓
Verifying project structure...            ✓
Validating config schema...               ✓
Validation successful!

Error example:

Error: Missing required field 'title' in manifest
Error: Version '1.0' does not follow semver format (use '1.0.0')
Error: Config schema is not valid JSON

flutch graph register

Prerequisites: Must have graph.manifest.json in current directory

bash
flutch graph register

What it does:

Validates local graph manifest
Creates dev-version entry on platform (e.g., acme.my-workflow::dev)
Creates test agent automatically in your workspace
Saves test agent API key to .flutch/dev-config.json

Options:

Option	Description
`--api-key <key>`	Use existing API key instead of creating new one
`--agent-name <name>`	Custom name for test agent (default: `{graphName}-dev`)

Output:

Registering graph acme.my-workflow::dev...
Creating test agent...                       ✓

Test agent created: acme.my-workflow-dev
API Key: flutch_dev_abc123xyz...

Configuration saved to .flutch/dev-config.json

Next steps:
  npm run dev                 # Start local graph server
  flutch graph test "Hello"   # Test via platform

flutch graph update

Update existing graph metadata.

bash
flutch graph update

Updates:

Graph title and description
Visibility settings
Default version
Configuration schema

Interactive mode: Prompts for values to update

Options:

bash
# Update specific fields
flutch graph update --title "New Title"
flutch graph update --description "Updated description"
flutch graph update --visibility public

flutch graph deploy

Deploy graph to Flutch platform.

bash
flutch graph deploy

What it does:

Validates manifest
Builds project (TypeScript compilation, Python packaging)
Uploads to Flutch
Registers/updates graph
Creates new version

Options:

bash
# Dry run (validate without deploying)
flutch graph deploy --dry-run

# Force deploy (skip validation)
flutch graph deploy --force

Output:

Validating manifest...                    ✓
Building graph package...                 ✓
Uploading to Flutch...                    ✓
Deploying acme.support-agent::1.0.0...    ✓
Deployment successful!

View graph in console: https://console.flutch.ai/graphs/abc123
Create agent: https://console.flutch.ai/graphs/abc123/create-agent

flutch graph list

List all your graphs.

bash
flutch graph list

Output:

Your Graphs:

acme.support-agent
  ├─ 1.0.0 (stable)     [default]
  ├─ 1.1.0 (stable)
  └─ dev

acme.sales-bot
  └─ 1.0.0 (stable)     [default]

With details:

bash
flutch graph list --verbose

flutch graph info

Get detailed information about a graph.

bash
flutch graph info <graph-type>

Examples:

bash
flutch graph info acme.support-agent
flutch graph info acme.support-agent::1.0.0

Output:

Graph: acme.support-agent
Title: Customer Support Agent
Description: AI agent for customer support
Visibility: public

Versions:
  1.0.0 (stable)            [default]
    Released: 2025-01-01
    Status: Active
    Agents using: 15

  1.1.0 (beta)
    Released: 2025-02-01
    Status: Active
    Agents using: 3

flutch graph test

Send test message through platform to local graph.

Prerequisites:

Graph registered with flutch graph register
Local graph server running (npm run dev)

bash
flutch graph test "<message>"

How it works:

CLI sends request to platform
Platform creates thread and operation
Platform calls your local endpoint
Local graph executes and returns response
Platform receives trace and logs
CLI displays response

Examples:

bash
# Basic test
flutch graph test "Hello, how are you?"

# Continue conversation
flutch graph test "Tell me more" --thread-id thread_abc123

# Custom endpoint
flutch graph test "Help" --endpoint http://localhost:8000

# Open console after test
flutch graph test "Debug this" --open-console

Options:

Option	Description
`--thread-id <id>`	Continue existing conversation
`--endpoint <url>`	Override local graph endpoint (default: http://localhost:3100)
`--open-console`	Open console UI in browser after test
`--stream`	Stream response in real-time

Output:

Sending to platform...                        ✓
Calling local graph...                        ✓
Uploading trace to platform...                ✓

Response:
Hello! I'm doing well, thank you for asking. How can I help you today?

Metadata:
  Thread ID: thread_abc123
  Tokens: 45
  Duration: 1.2s
  Nodes executed: router → tools → generate

View full trace: https://console.flutch.ai/traces/trace_xyz789

flutch graph add-version

Add a new version to existing graph.

bash
flutch graph add-version <version>

Examples:

bash
# Add new version
flutch graph add-version 1.1.0

# Add version with description
flutch graph add-version 1.2.0 --description "Added new features"

What it does:

Creates version directory structure
Copies files from previous version (optional)
Updates manifest

flutch graph publish

Publish graph version to make it available for agents.

bash
flutch graph publish <version>

Examples:

bash
# Publish version
flutch graph publish 1.0.0

# Publish and set as default
flutch graph publish 1.0.0 --default

Options:

Option	Description
`--default`	Set as default version for new agents
`--stability`	Set stability level (`stable`, `beta`, `alpha`)

Model Catalog Commands

Manage AI models available in your workspace.

flutch model-catalog list

List all available models.

bash
flutch model-catalog list

Output:

Available Models:

OpenAI:
  ├─ gpt-4o                 (chat)
  ├─ gpt-4o-mini            (chat)
  └─ text-embedding-3-small (embedding)

Anthropic:
  ├─ claude-3-5-sonnet      (chat)
  └─ claude-3-5-haiku       (chat)

Cohere:
  ├─ command-r-plus         (chat)
  └─ rerank-v3              (rerank)

With details:

bash
flutch model-catalog list --verbose

flutch model-catalog add

Add custom model to catalog.

bash
flutch model-catalog add

Interactive prompts:

Model ID
Display name
Provider
Model type (chat, embedding, rerank)
Context window
Pricing (optional)

Non-interactive:

bash
flutch model-catalog add \
  --id custom-gpt-4 \
  --name "Custom GPT-4" \
  --provider openai \
  --type chat \
  --context-window 128000

Tools Catalog Commands

Manage tools available for your graphs.

flutch tools-catalog list

List all available tools.

bash
flutch tools-catalog list

Output:

Available Tools:

Web & Search:
  ├─ web_search             Search the web
  ├─ web_scrape             Scrape webpage content
  └─ wikipedia_search       Search Wikipedia

Data & Files:
  ├─ read_file              Read file contents
  ├─ write_file             Write to file
  └─ list_directory         List directory contents

External APIs:
  ├─ sendgrid_email         Send email via SendGrid
  └─ stripe_payment         Process Stripe payment

flutch tools-catalog add

Add custom tool to catalog.

bash
flutch tools-catalog add

Interactive prompts:

Tool name
Description
Input schema (JSON)
MCP server details (optional)

Non-interactive:

bash
flutch tools-catalog add \
  --name custom_api_call \
  --description "Call custom API" \
  --schema ./tool-schema.json

flutch tools-catalog register

bash
flutch tools-catalog register <mcp-server-url>

Examples:

bash
# Register MCP server
flutch tools-catalog register https://mcp.example.com

# Register with custom name
flutch tools-catalog register https://mcp.example.com --name "Custom Tools"

What it does:

Connects to MCP server
Discovers available tools
Registers tools in catalog
Makes tools available for graphs