FlowDot CLI

The FlowDot CLI is a command-line AI agent that runs locally on your machine. Execute natural language tasks, run recipes with approval gates, and automate code workflows - all from your terminal.

Installation

Install FlowDot CLI globally via npm:

# Install globally
npm install -g "@flowdot.ai/cli"

# Login (opens browser for OAuth)
flowdot auth login

# Start the agent (primary usage)
flowdot

# Verify installation
flowdot --version

Authentication

FlowDot uses browser-based OAuth for secure authentication. Tokens are stored in your OS keychain:

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service (libsecret)

Core Agent

The core agent processes natural language requests and executes tasks on your local machine.

Start the Agent (Primary Usage)

# Just run flowdot to enter interactive agent chat mode
flowdot

# Once in chat, you can:
# - Ask it to update your code
# - Run workflows
# - Use recipes
# - Search the web
# - Analyze your codebase
# - And much more...

Quick Tasks

# One-off task (runs and exits)
flowdot "refactor this function to use async/await"

# With context file
flowdot "explain this code" --file ./src/index.ts

Interactive Chat

# Start interactive session (same as just running 'flowdot')
flowdot chat

# Shell escape (run command directly)
> !git status

# Exit chat
> exit

Chat Management

Recipe Execution

Recipes are multi-step agentic workflows that run locally with human approval gates. Design them on the web, execute them via CLI.

# Link a recipe to an alias
flowdot recipes link <hash> <alias>

# Run a recipe
flowdot recipes run <alias> "your task"

# Or use the shortcut
flowdot <alias> "your task"

Approval Gates

Recipes can include gate steps that pause for human approval. You'll see 5 response options:

• Yes - Right Now: Allow this single operation
• Yes - This Session: Allow until CLI restarts
• Yes - Forever: Persist permission permanently
• No Right Now: Deny this single operation
• No Not Ever: Permanently deny this type of action

Store Interpolation

Access recipe stores in prompts:

• {{inputs.request}} - The CLI task argument
• {{stores.result}} - A store value

Code Tools

The CLI has built-in tools for code analysis and modification:

Permission System

FlowDot asks for permission before performing sensitive operations. You have 5 response options:

Permission Categories

• command-execute - Shell command execution
• file-read - Reading files
• file-write - Writing/editing files
• file-create - Creating new files
• web-search - Internet searches

Managing Permissions

# View current permissions
flowdot permissions

# Reset all permissions
flowdot permissions --reset

Model Configuration

Configure which LLM models to use for different task complexities.

# Interactive model browser
flowdot models

# Set tier model
flowdot config set-model simple
flowdot config set-model capable
flowdot config set-model complex

Tier Mapping

• Simple: Fast, cost-effective tasks (gpt-4o-mini, claude-haiku)
• Capable: Balanced performance (gpt-4o, claude-sonnet)
• Complex: Maximum capability (o1, claude-opus)

COMMS Relay System

Control your CLI remotely via Telegram or Discord. Approve permissions, send commands, and receive output from anywhere.

Enable Relay Mode

# In chat mode
> /relay telegram
# or
> /relay discord

Features

• Bidirectional Communication: CLI output mirrors to your chat channel
• Permission Prompts via Mobile: Approve file writes, command execution remotely
• 5-Button Approval: Full permission options in chat apps
• Inbound Commands: Send commands from chat to execute in CLI

Daemon Mode

Run the CLI as a background listener that receives commands from Telegram/Discord.

# Start daemon
flowdot agent --listen

# Daemon runs in background, receiving:
# - Commands from chat integrations
# - Recipe execution requests
# - Has full local file access

Heartbeat

The daemon maintains automatic keepalive with the FlowDot Hub to stay connected.

Loops System

Schedule recurring tasks that run automatically in the background.

# Run every 5 minutes
flowdot loop 5m "check for new issues and summarize"

# Run every hour
flowdot loop 1h "generate daily report"

# Run with cron syntax
flowdot loop "0 9 * * *" "morning standup summary"

Loop Management

Safety Features

• Background Daemon: Survives terminal close
• Auto-Expiration: Default 3-day limit for safety
• Interval Formats: Minutes (5m), hours (1h), days (1d), cron

Workflow Integration

Invoke server-side workflows from the CLI.

# Browse available workflows
flowdot workflows

# Invoke a workflow
flowdot workflow run <hash> --input '{"key": "value"}'

Related Documentation