---
name: vr-setup-auth
description: Set up the VoiceRun CLI environment and authenticate. Installs dependencies, configures AI integrations, and signs in to the VoiceRun platform.
---

# Set Up and Authenticate VoiceRun CLI

You are helping the user set up the VoiceRun CLI and authenticate with the platform. Follow these steps:

## Step 1: Install the CLI

If the CLI is not yet installed, help the user install it:

```bash
pip install voicerun-cli
```

Or with uv:

```bash
uv tool install voicerun-cli
```

Verify the installation:

```bash
vr --version
```

## Step 2: Run setup

Run the setup command to install dependencies and configure integrations:

```bash
vr setup
```

This installs:
1. **uv** — Python package manager (for dependency management)
2. **Helm CLI** — Template rendering engine (for agent configuration)
3. **Skills** — AI-assisted workflow skills for coding agents
4. **MCP server** — Model Context Protocol configuration for IDE integrations

### Setup options

The setup command will interactively prompt for which targets to install skills and MCP configuration to. You can also specify targets directly:

| Flag | Description |
|------|-------------|
| `--claude-code` | Install skills and MCP to Claude Code |
| `--codex` | Install skills to Codex CLI |
| `--openclaw` | Install skills to OpenClaw |
| `--cursor` | Configure MCP for Cursor |
| `--windsurf` | Configure MCP for Windsurf |
| `--skip-uv` | Skip uv installation |
| `--skip-helm` | Skip Helm installation |
| `--skip-skills` | Skip skills installation |
| `--skip-mcp` | Skip MCP configuration |

```bash
# Install everything for Claude Code
vr setup --claude-code

# Install for multiple targets
vr setup --claude-code --cursor
```

## Step 3: Sign in

Authenticate with the VoiceRun platform:

```bash
vr signin
```

Three authentication methods are available:

1. **Web browser** (recommended) — Opens your default browser for OAuth authentication
2. **Email/Password** — Enter credentials directly in the terminal
3. **API Key** — Use an API key for non-interactive authentication

For non-interactive sign in (useful in CI/CD or scripting):

```bash
# Sign in with API key
vr signin --api-key YOUR_API_KEY

# Sign in with email/password
vr signin --email user@example.com --password yourpassword
```

Credentials are stored in `~/.voicerun/`:
- Cookie: `~/.voicerun/cookie`
- API Key: `~/.voicerun/apikey`
- Config: `~/.voicerun/config.json`

## Step 4: Verify authentication

Run a simple command to verify you're authenticated:

```bash
vr get agents
```

If this returns a list of agents (or an empty table), authentication is working.

## Step 5: Configure context (optional)

If you work with multiple VoiceRun environments (staging, production, etc.), configure contexts:

```bash
# View current context
vr context current

# List available contexts
vr context list

# Switch context
vr context switch production

# Create a custom context
vr context create staging https://api.staging.voicerun.com https://app.staging.voicerun.com
```

If your account belongs to multiple organizations, set the active organization:

```bash
vr context set-org org_123456
```

## Step 6: Update the CLI (ongoing)

Keep the CLI up to date:

```bash
vr --update
# or
vr -U
```

This upgrades the `voicerun-cli` package and refreshes all installed skills and MCP server configurations for the targets selected during `vr setup`.

## Troubleshooting

- **"Command not found: vr"** — The CLI is not installed or not on your PATH. Reinstall with `pip install voicerun-cli` or `uv tool install voicerun-cli`.
- **"Authentication required"** — Run `vr signin` to authenticate.
- **"Failed to open browser"** — Use email/password or API key method instead: `vr signin --api-key YOUR_KEY`.
- **Sign out** — Run `vr signout` to clear stored credentials.
- **Wrong organization** — Use `vr context set-org <ORG_ID>` to switch organizations, or `vr context set-org ""` to clear the override.

Guide the user through each step, confirming success before proceeding to the next.
