Skyvern/fern/integrations/cli.mdx

---
title: CLI & Skills
subtitle: Automate browsers and manage workflows from the command line
slug: integrations/cli
---

The `skyvern` CLI gives you direct access to browser automation, workflow management, credential storage, and more — all from your terminal. Use it in shell scripts, CI/CD pipelines, or for quick one-off tasks.

## Install

```bash
pip install skyvern
```

## Getting started

Two commands to go from install to working MCP:

```bash
skyvern login   # opens browser, authenticates, saves API key
skyvern setup   # auto-detects your AI tools, configures MCP for all of them
```

`login` handles both new signups and returning users. `setup` detects Claude Code, Cursor, Windsurf, and Claude Desktop, then writes the correct MCP config for each one. Pass `--api-key YOUR_KEY` to either command if you already have a key.

<Tip>
Don't want to install the CLI? You can also copy-paste the MCP config JSON directly — see [MCP Server](/integrations/mcp) for the zero-install path.
</Tip>

## Command reference

### Onboarding

```bash
skyvern login                 # Authenticate via browser — saves API key locally
skyvern setup                 # Auto-detect AI tools and configure MCP for all of them
```

### Services

```bash
skyvern run server            # Start the local API server
skyvern run mcp               # Start the MCP server (stdio transport)
skyvern run mcp --http        # Start the MCP server (HTTP transport)
skyvern status                # Check if services are running
skyvern stop                  # Stop running services
```

### Browser automation

All browser commands operate on an active session. Create one first, then run actions against it.

```bash
# Browser session management
skyvern browser session create              # Start a cloud browser session
skyvern browser session create --timeout 30 # Custom timeout (minutes)
skyvern browser session list                # List active sessions
skyvern browser session get --session pbs_xxx
skyvern browser session connect --cdp ws://localhost:9222  # Connect to local Chrome
skyvern browser session close               # Close the active session

# Navigation
skyvern browser navigate --url https://example.com

# AI-powered actions
skyvern browser act --prompt "Click the Sign In button"
skyvern browser extract --prompt "Get all product names and prices"
skyvern browser validate --prompt "Is the user logged in?"

# Precision actions (CSS/XPath selectors or natural language intent)
skyvern browser click --selector "#submit-btn"
skyvern browser click --intent "the checkout button"
skyvern browser type --selector "#email" --text "user@example.com"
skyvern browser select --selector "#country" --value "US"
skyvern browser scroll --direction down --amount 500
skyvern browser press-key --key Enter
skyvern browser hover --selector ".menu-item"
skyvern browser wait --selector "#results" --state visible

# Screenshots
skyvern browser screenshot
skyvern browser screenshot --full-page --output page.png

# Run JavaScript
skyvern browser evaluate --expression "document.title"

# Full task automation (multi-step agent)
skyvern browser run-task --prompt "Find the cheapest flight from NYC to LA"
skyvern browser login --url https://app.example.com --credential-id cred_xxx
```

<Tip>
Every browser command supports `--json` for machine-readable output, and `--session` / `--cdp` to target a specific session. If omitted, the CLI uses the last active session automatically.
</Tip>

### Local browser serve

Expose your local Chrome to Skyvern Cloud so tasks can access localhost, internal tools, and your existing login sessions.

```bash
# Launch with ngrok tunnel and your Chrome profile's cookies/logins
skyvern browser serve --tunnel --use-local-profile

# Use a specific Chrome profile
skyvern browser serve --tunnel --use-local-profile --chrome-profile-name "Profile 2"

# Headless mode with JSON output (for scripting)
skyvern browser serve --tunnel --headless --json
```

The `--use-local-profile` flag clones cookies and saved passwords from your Chrome profile into the served browser. Your original profile is never modified, and it works while Chrome is open.

<Warning>
Always pass `--api-key` when using `--tunnel`. Without it, anyone with the ngrok URL has full browser control.
</Warning>

### Workflows

```bash
skyvern workflow list                              # List all workflows
skyvern workflow get --workflow-id wpid_xxx         # Get workflow details
skyvern workflow create --file workflow.json         # Create from JSON definition
skyvern workflow update --workflow-id wpid_xxx --file updated.json
skyvern workflow delete --workflow-id wpid_xxx
skyvern workflow run --workflow-id wpid_xxx          # Execute a workflow
skyvern workflow run --workflow-id wpid_xxx --params '{"url": "https://example.com"}'
skyvern workflow status --run-id wr_xxx              # Check run status
skyvern workflow cancel --run-id wr_xxx              # Cancel a running workflow
```

### Credentials

Credentials are created interactively via stdin so secrets never appear in shell history.

```bash
skyvern credentials add            # Interactive credential creation (password or credit card)
skyvern credential list            # List stored credentials
skyvern credential get --id cred_xxx
skyvern credential delete --id cred_xxx
```

Note: `credentials` (plural) is used for the interactive `add` command; `credential` (singular) for list/get/delete. Both forms are intentional.

### Workflow blocks

```bash
skyvern block schema --block-type task     # Show the JSON schema for a block type
skyvern block validate --file block.json   # Validate a block definition
```

### MCP setup

Register Skyvern's MCP server with your AI coding tools:

```bash
skyvern setup                        # Auto-detect all tools and configure at once
skyvern setup claude-code            # Auto: .mcp.json in a project, ~/.claude.json otherwise
skyvern setup claude-code --project  # Force project-local Claude Code config
skyvern setup claude-code --global   # Force global Claude Code config
skyvern setup claude-code --skip-skills  # MCP only, no skills
skyvern setup claude                 # Configure Claude Desktop only
skyvern setup cursor                 # Configure Cursor only
skyvern setup windsurf               # Configure Windsurf only
skyvern mcp switch                   # Interactively switch existing Skyvern MCP configs
skyvern mcp switch --dry-run         # Preview changes without writing files
skyvern mcp profile list             # List saved switch sources
skyvern mcp profile save work-prod --api-key YOUR_KEY --base-url https://api.skyvern.com
```

Use bare `skyvern setup` to configure everything at once. The per-tool subcommands are for when you only want to target one tool.

`skyvern setup claude-code` writes the MCP config **and** copies bundled skills (including `/qa`) into your project's `.claude/skills/` directory. In a project, the default target is `.mcp.json`; use `--global` to override. Use `--skip-skills` to opt out.

For Claude Desktop on macOS or Windows, the recommended no-Node path is the downloadable `.mcpb` bundle in [MCP Server](/integrations/mcp). `skyvern setup claude` still writes the manual `mcp-remote` JSON bridge, so remote mode requires Node.js unless you use the bundle.

`skyvern mcp switch` updates existing Skyvern entries in Claude Code, Claude Desktop, Cursor, Windsurf, and Codex configs. It lets you choose a source from env, saved profiles, existing configs already on disk, or manual entry; creates backups before writing; and preserves the config's current transport shape. If a tool has no Skyvern entry yet, run `skyvern setup` first.

### Self-hosted setup

These commands are for running Skyvern on your own infrastructure. If you're using Skyvern Cloud, you don't need them — `skyvern login` + `skyvern setup` is all you need.

```bash
skyvern init                     # Full interactive wizard (PostgreSQL, LLM providers, browser, .env)
skyvern init browser             # Initialize browser configuration only
skyvern quickstart               # One-command init + start
```

For the local self-hosted Claude Code path, `skyvern quickstart` or `skyvern init` can also configure MCP during the interactive wizard. In a project directory that flow writes `.mcp.json`, installs `.claude/skills/qa`, and keeps the connection fully local for localhost testing.

### Other

```bash
skyvern docs                     # Open documentation in your browser
```

## CLI vs MCP: when to use which

| Use case | CLI | MCP |
|----------|-----|-----|
| Shell scripts and CI/CD | Yes | No |
| One-off browser tasks | Yes | Yes |
| AI assistant integration (Claude, Cursor, Codex) | No | Yes |
| Credential creation (secrets via stdin) | Yes | No |
| Starting/stopping services | Yes | No |
| Composing with Unix pipes (`--json` output) | Yes | No |
| Natural language orchestration by an AI agent | No | Yes |

The CLI and MCP server share the same underlying logic. The CLI is for humans and scripts; MCP is for AI assistants that call tools programmatically.

## Skills

Skills are bundled markdown files that teach AI coding tools how to use Skyvern. They ship with `pip install skyvern` and are **automatically installed** when you run `skyvern setup claude-code` or choose Claude Code during `skyvern init` / `skyvern quickstart`.

| Skill | What it does |
|-------|-------------|
| **qa** | Reads your `git diff`, generates browser tests, runs them against your dev server, reports pass/fail with screenshots. Invoke with `/qa` in Claude Code. |
| **skyvern** | CLI reference covering all browser automation, workflow, and credential commands. |
| **testing** | Smoke tests for verifying Skyvern deployments. |

```bash
skyvern skill list                  # List available skills
skyvern skill show qa               # Render a skill in the terminal
skyvern skill copy --output .claude/skills  # Copy all skills manually
skyvern skill copy qa -o .claude/skills     # Copy a single skill
```

<Accordion title="Loading skills into AI tools">

Skills are plain markdown files. Load them into any AI coding tool that supports custom instructions:

**Claude Code** — run `skyvern quickstart` or `skyvern init`, then choose Claude Code during MCP setup. You can also run `skyvern setup claude-code` later. Both paths register the MCP server and install skills into `.claude/skills/`. The `/qa` skill is immediately available.

**Codex** — copy skills into your project's `.codex/skills/` directory:

```bash
skyvern skill copy -o .codex/skills/
```

**Any tool** — point your tool at the file path returned by `skyvern skill path qa`.

</Accordion>

## JSON output

All commands support `--json` for structured output, making it easy to compose with `jq` and other tools:

```bash
# Extract the session ID from a new session
SESSION=$(skyvern browser session create --json | jq -r '.session_id')

# Extract data and pipe to a file
skyvern browser extract --prompt "Get all links" --json | jq '.extracted' > links.json

# Check workflow run status in a script
STATUS=$(skyvern workflow status --run-id wr_xxx --json | jq -r '.status')
```

## Troubleshooting

<Accordion title="Command not found: skyvern">
Make sure the package is installed and on your PATH:

```bash
pip install skyvern
which skyvern
```

If using a virtual environment, activate it first. You can also run via module:

```bash
python3 -m skyvern --help
```
</Accordion>

<Accordion title="Authentication errors">
Verify your API key is set:

```bash
echo $SKYVERN_API_KEY
```

You can also pass it directly:

```bash
skyvern credentials add --api-key YOUR_KEY
```

Get an API key from [Settings](https://app.skyvern.com/settings/api-keys) in the Skyvern dashboard.
</Accordion>

<Accordion title="No active browser session">
Browser commands require an active session. Create one first:

```bash
skyvern browser session create
```

Or specify a session explicitly:

```bash
skyvern browser navigate --url https://example.com --session pbs_xxx
```
</Accordion>