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

# Agents Management

> Manage AI agents with the CLI - deploy, clone, duplicate, and delete

The `rf agents` command (or `rf agent` singular) provides complete agent management capabilities with an **interactive menu** and support for automation via non-interactive flags.

## Commands Overview

| Command               | Description                       |
| --------------------- | --------------------------------- |
| `rf agents list`      | Interactive menu to manage agents |
| `rf agents get`       | Show current agent details        |
| `rf agents clone`     | Clone agent repository locally    |
| `rf agents pull`      | Pull latest changes from server   |
| `rf agents deploy`    | Deploy local changes to server    |
| `rf agents duplicate` | Duplicate agent on server         |
| `rf agents delete`    | Delete agent                      |

## Interactive Menu

### List Agents

List all available agents with an interactive menu:

```bash theme={null}
rf agents list
```

This opens an **interactive menu** where you can:

* 📋 **Browse** all your agents
* 🔽 **Clone** repository to local machine
* 🚀 **Deploy** changes to server
* 📋 **Duplicate** agent on server
* 🗑️ **Delete** agent
* 👁️ **View** agent details

<Tip>
  The interactive menu is the fastest way to manage agents - no need to remember multiple commands!
</Tip>

## Main Commands

### Get Agent Details

Show details of the current/selected agent:

```bash theme={null}
rf agents get
```

**Output:**

```
Agent: support-bot
ID: agent_abc123
Tenant: ACME Corp (tenant_xyz)
Created: 2024-01-15
Status: Active
Repository: https://github.com/runflow-agents/support-bot
```

### Clone Agent Repository

Download an agent repository to your local machine:

```bash theme={null}
rf agents clone
```

Or use the interactive menu (`rf agents list` → select agent → Clone repository).

This creates a local folder with the agent's code, allowing you to:

* Make changes locally
* Test changes with `rf test`
* Deploy updates with `rf agents deploy`

**What gets cloned:**

```
agent-name/
├── .runflow/
│   └── rf.json         # Agent configuration
├── src/
│   └── index.ts        # Agent code
├── package.json
└── README.md
```

### Deploy Changes

Deploy your local changes to the server:

```bash theme={null}
cd my-agent/
rf agents deploy
```

<Tip>
  Make sure you're in the agent's directory before deploying. The CLI detects the agent from `.runflow/rf.json`.
</Tip>

**Deployment Process:**

1. Validates `.runflow/rf.json` exists
2. Commits local changes to git
3. Pushes to remote repository
4. Server automatically rebuilds agent
5. Agent is live with new changes

### Pull Latest Changes

Pull the latest changes from the server (overwrites local changes):

```bash theme={null}
cd my-agent/
rf agents pull
```

<Warning>
  This command will overwrite your local changes. Make sure to commit or backup your work before pulling.
</Warning>

**When to use:**

* After changes made via dashboard
* Sync with team member changes
* Reset to server state

### Duplicate Agent

Create a copy of an agent on the server:

```bash theme={null}
rf agents duplicate
```

Or use the interactive menu (`rf agents list` → select agent → Duplicate).

**Use cases:**

* Create dev/staging versions
* Fork agent for different client
* Experiment without affecting original

### Delete Agent

Delete an agent from the server:

```bash theme={null}
# With confirmation prompt
rf agents delete

# Skip confirmation (for scripts/automation)
rf agents delete --yes
rf agents delete -y
```

Or use the interactive menu (`rf agents list` → select agent → Delete).

<Warning>
  This action is permanent and cannot be undone! The agent and its repository will be deleted.
</Warning>

## Non-Interactive Mode

All commands support `--yes` or `-y` flag to skip confirmations, perfect for automation:

```bash theme={null}
# Delete without confirmation
rf agents delete --yes

# Use in scripts
#!/bin/bash
rf agents delete --yes
echo "Agent deleted"
```

## Common Workflows

### Development Workflow

```bash theme={null}
# 1. Create new agent
rf create --name my-agent --template starter --yes

# 2. Navigate to agent folder
cd my-agent/

# 3. Make your changes
# ... edit src/index.ts ...

# 4. Test locally
rf test

# 5. Deploy changes
rf agents deploy

# 6. Pull latest changes when needed (if changed via dashboard)
rf agents pull
```

### Existing Agent Workflow

```bash theme={null}
# 1. List and select agent (interactive menu)
rf agents list

# 2. Clone repository (select "Clone repository" from menu)
# This creates a folder with the agent name

# 3. Navigate to agent folder
cd agent-name/

# 4. Make your changes
# ... edit files ...

# 5. Test locally
rf test

# 6. Deploy changes
rf agents deploy
```

### Staging-to-Production Workflow

Runflow has two environments per tenant: **staging** and **production**. `rf agents deploy` always deploys to staging. When staging is validated, promote it to production.

```bash theme={null}
# 1. Make your changes and test locally (runs in staging mode)
cd my-agent/
rf test

# 2. Deploy to staging
rf agents deploy

# 3. Validate on the staging endpoint
# ... run real traffic through the staging endpoint URL ...

# 4. Promote staging to production when ready
rf agents promote
```

<Tip>
  For the full environment model — which entities are per-environment, how to publish prompts and connectors, and how the dashboard Releases screen works — see [Environments](/core-concepts/environments).
</Tip>

### Agent Duplication & Experimentation

```bash theme={null}
# Duplicate agent for testing
rf agents list
# → Select agent → Duplicate
# → Enter new name: "my-agent-experimental"

# Clone and test
rf agents clone  # Select experimental version
cd my-agent-experimental/
# ... make experimental changes ...
rf test
rf agents deploy

# If successful, apply to original
cd ../my-agent/
# ... apply changes ...
rf agents deploy

# Delete experimental version
rf agents delete --yes
```

## Project Configuration

Each agent folder contains `.runflow/rf.json`:

```json theme={null}
{
  "agentId": "agent_abc123",
  "agentName": "my-agent",
  "tenantId": "tenant_xyz"
}
```

<Warning>
  Don't delete or modify `.runflow/rf.json` - it's required for deployment and local testing!
</Warning>

## Using with AI Tools

Non-interactive mode works seamlessly with AI coding assistants:

```bash theme={null}
# Cursor / Copilot can execute these
rf agents delete --yes
rf agents deploy
rf agents pull
```

## Automation Scripts

### Bulk Deployment

```bash theme={null}
#!/bin/bash

agents=("support-bot" "sales-assistant" "feedback-analyzer")

for agent in "${agents[@]}"; do
  cd "$agent"
  rf test
  if [ $? -eq 0 ]; then
    rf agents deploy
  else
    echo "Tests failed for $agent"
  fi
  cd ..
done
```

### CI/CD Integration

```bash theme={null}
# .github/workflows/deploy.yml
name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install CLI
        run: npm i -g @runflow-ai/cli
      - name: Login
        run: rf login --api-key ${{ secrets.RUNFLOW_API_KEY }}
      - name: Deploy
        run: rf agents deploy
```

## Troubleshooting

### Not in Agent Directory

```bash theme={null}
rf agents deploy
# Error: No agent configuration found (.runflow/rf.json)
```

**Solution:** Navigate to agent directory:

```bash theme={null}
cd my-agent/
rf agents deploy
```

### Merge Conflicts on Pull

```bash theme={null}
rf agents pull
# Error: Local changes conflict with server
```

**Solution:**

```bash theme={null}
# Commit local changes first
git add .
git commit -m "Local changes"

# Then pull
rf agents pull

# Or discard local changes
git reset --hard HEAD
rf agents pull
```

### Deployment Failed

```bash theme={null}
rf agents deploy
# Error: Deployment failed
```

**Solution:**

* Check for syntax errors in your code
* Verify all dependencies are in `package.json`
* Check server logs via dashboard
* Ensure valid `.runflow/rf.json`

## Aliases

You can use either `rf agents` (plural) or `rf agent` (singular):

```bash theme={null}
rf agent list      # Same as rf agents list
rf agent deploy    # Same as rf agents deploy
rf agent clone     # Same as rf agents clone
rf agent delete -y # Same as rf agents delete -y
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Agent" icon="plus" href="/cli/create">
    Create new agent from template
  </Card>

  <Card title="Test" icon="flask" href="/cli/test">
    Test agents locally with web interface
  </Card>

  <Card title="Knowledge Base" icon="database" href="/cli/kb">
    Add knowledge base for RAG
  </Card>

  <Card title="Prompts" icon="file-lines" href="/cli/prompts">
    Manage prompt templates
  </Card>
</CardGroup>