npm package: @runflow-ai/cli
Description: Official CLI for RunFlow AI platform - manage agents, deploy code, and interact with AI workflows from your terminal
Author: RunFlow AI
Latest version: 0.2.42

# RunFlow CLI

Command line interface to manage AI agents via **API Portal**. Create agents, manage knowledge bases, handle prompts — all from the terminal.

## Key Features

- 🚀 **Create agents from templates** with `rf create`
- 🧠 **Manage knowledge bases** (vector stores) with `rf kb`
- 📝 **Full prompts management** with CRUD and editor integration
- 👥 **Multi-tenant profiles** - switch between API keys easily
- 🧪 **Local testing** with web interface and live reload

## 📦 Installation

```bash
npm i -g @runflow-ai/cli
```

## ⚡ Quick Start

```bash
# 1. Authenticate with your API key
rf login

# 2. Create a new agent from template
rf create

# 3. Navigate to the created folder
cd my-agent/

# 4. Test locally with web interface
rf test

# 5. Deploy to production
rf agents deploy
```

## 🛠️ Commands

### `rf create` - Create New Agent ⭐

Interactive agent creation with templates from the API.

```bash
# Interactive mode
rf create

# Non-interactive mode (for scripts/AI)
rf create --name my-agent --template starter
rf create -n my-agent -t rag-agent --yes
```

**Options:**
- `-n, --name <name>` - Agent name (non-interactive)
- `-t, --template <id>` - Template ID or name (non-interactive)
- `-y, --yes` - Auto-install dependencies without prompting

**Flow:**
1. Enter agent name (or use `--name`)
2. Choose template (or use `--template`)
3. Agent created on server with repository
4. Repository cloned locally
5. Dependencies installed (auto with `--yes`)

**Available Templates:**
- **starter** - Minimal setup, perfect for beginners
- **rag-agent** - Agent with knowledge base integration
- **webhook-handler** - Process webhooks and integrations

---

### `rf login` - Authentication

```bash
# Interactive login
rf login

# With API key directly
rf login --api-key sk-xxx...

# Save as named profile
rf login --profile client-acme
```

**Options:**
- `--api-key <key>` - API key to use
- `--profile <name>` - Save as named profile
- `--api <url>` - Custom API URL

---

### `rf switch` - Switch Profile

Switch between saved profiles for multi-tenant support.

```bash
# Interactive selection
rf switch

# Direct switch
rf switch client-acme
```

---

### `rf profiles` - Manage Profiles

```bash
# List all profiles
rf profiles

# Show current profile
rf profiles current

# Delete a profile
rf profiles delete client-acme
```

---

### `rf agents` - Agent Management

```bash
rf agents list              # List agents (interactive menu)
rf agents get               # Show current agent details
rf agents clone             # Clone agent repository
rf agents pull              # Pull latest changes
rf agents deploy            # Deploy local changes
rf agents duplicate         # Duplicate agent
rf agents delete            # Delete agent
rf agents delete --yes      # Delete without confirmation
```

**Options:**
- `-y, --yes` - Skip confirmation prompts

**Aliases:** `rf agent`

---

### `rf prompts` - Prompts Management

Full CRUD operations for prompt templates.

```bash
# Interactive mode
rf prompts

# List all prompts
rf prompts list

# Get prompt content
rf prompts get <name>

# Create new prompt (interactive)
rf prompts create <name>

# Create prompt (non-interactive - for scripts/AI)
rf prompts create my-prompt --content "You are a helpful assistant"
rf prompts create my-prompt --file ./prompt.txt

# Update prompt (opens editor)
rf prompts update <name>
rf prompts update <name> --content "New content"

# Delete prompt
rf prompts delete <name>
rf prompts delete <name> --yes  # Skip confirmation

# Render with variables
rf prompts render <name> '{"var": "value"}'
```

**Options:**
- `-c, --content <text>` - Prompt content (non-interactive)
- `-f, --file <path>` - Read content from file
- `-y, --yes` - Skip confirmation prompts

**Aliases:** `rf prompt`

---

### `rf kb` - Knowledge Base Management

Manage vector stores for RAG (Retrieval Augmented Generation).

```bash
# List all knowledge bases
rf kb list

# Create new knowledge base (interactive)
rf kb create <name>

# Create KB (non-interactive - for scripts/AI)
rf kb create my-kb --embedding "OpenAI Small"
rf kb create my-kb -e openai-small

# Upload file
rf kb upload <kb-name> <file>

# Upload directory (with confirmation skip)
rf kb upload <kb-name> ./docs --yes

# Check processing status
rf kb status <kb-name>

# List documents
rf kb docs <kb-name>

# Remove document
rf kb remove-doc <kb-name> <doc-id>
rf kb remove-doc <kb-name> <doc-id> --yes  # Skip confirmation

# Semantic search
rf kb search <kb-name> "your query"

# Delete knowledge base
rf kb delete <kb-name>
rf kb delete <kb-name> --yes  # Skip confirmation
```

**Options:**
- `-e, --embedding <config>` - Embedding config ID or name (non-interactive)
- `-y, --yes` - Skip confirmation prompts

**Supported Files:** PDF, TXT, MD, DOCX

---

### `rf test` - Local Testing

Start local development server with web interface.

```bash
cd my-agent/
rf test

# Custom port
rf test --port 4000

# Without opening browser
rf test --no-browser
```

**Features:**
- Zero config - auto-detects from `.runflow/rf.json`
- Web portal with real-time monitoring
- Live reload on file changes
- Traces saved to `.runflow/traces.json`

---

### Other Commands

```bash
rf users list               # Manage users
rf credentials list         # List credentials
rf triggers list            # Manage triggers
rf executions list          # View execution history
rf health                   # Check API health
```

## 📖 Usage Examples

### Complete Development Workflow

```bash
# 1. Login and create agent
rf login
rf create
# → Select "RAG Agent" template
# → Name: "support-bot"

# 2. Navigate and set up knowledge base
cd support-bot/
rf kb create support-docs
rf kb upload support-docs ./docs --recursive

# 3. Test locally
rf test

# 4. Deploy to production
rf agents deploy
```

### Multi-Tenant Workflow

```bash
# Save profiles for different clients
rf login --profile acme-corp
rf login --profile tech-startup

# Switch between clients
rf switch acme-corp
rf agents list

rf switch tech-startup
rf agents list
```

### Knowledge Base Management

```bash
# Create and populate KB
rf kb create product-docs
rf kb upload product-docs ./manual.pdf
rf kb upload product-docs ./faq.md

# Check status
rf kb status product-docs

# Test search
rf kb search product-docs "how to reset password"

# Manage documents
rf kb docs product-docs
rf kb remove-doc product-docs doc_123
```

### Using with AI Tools / Scripts (Non-Interactive Mode)

All commands support non-interactive flags for automation with AI tools (Cursor, Copilot) or CI/CD:

```bash
# Create agent without interaction
rf create --name my-agent --template starter --yes

# Create prompt without interaction
rf prompts create support-bot --content "You are a support assistant"

# Create KB without interaction  
rf kb create docs-kb --embedding "OpenAI Small"

# Delete without confirmation
rf agents delete --yes
rf prompts delete old-prompt --yes
rf kb delete old-kb --yes

# Upload directory without confirmation
rf kb upload docs-kb ./documents --yes
```

**Flag Reference:**

| Command | Specific Flags | Common Flags |
|---------|---------------|--------------|
| `rf create` | `-n, --name` `-t, --template` | `-y, --yes` |
| `rf agents` | - | `-y, --yes` |
| `rf prompts` | `-c, --content` `-f, --file` | `-y, --yes` |
| `rf kb` | `-e, --embedding` | `-y, --yes` |

All commands also support: `--api-key` and `--api` for authentication overrides.

## 🔧 Configuration

### Environment Variables

```bash
RUNFLOW_API_URL=https://api.runflow.ai
RUNFLOW_API_KEY=sk-xxx...
```

### Config File (`~/.runflowrc`)

```json
{
  "currentProfile": "default",
  "profiles": {
    "default": {
      "apiKey": "sk-xxx...",
      "apiUrl": "https://api.runflow.ai",
      "tenantId": "tenant_123",
      "tenantName": "My Company"
    }
  }
}
```

### Project Config (`.runflow/rf.json`)

Created automatically by `rf create` or `rf agents clone`:

```json
{
  "agentId": "agent_uuid",
  "agentName": "my-agent",
  "tenantId": "tenant_123"
}
```

## 📝 License

MIT – (c) IFTL 2025