CLI & Skills | Skyvern

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

$ pip install skyvern

Getting started

Two commands to go from install to working MCP:

$ 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.

Don’t want to install the CLI? You can also copy-paste the MCP config JSON directly — see MCP Server for the zero-install path.

Command reference

Onboarding

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

Services

$ 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.

$ # 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

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.

Local browser serve

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

$ # 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.

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

Workflows

$ 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.

$ 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

$ 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

$ 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. 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.

$ 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

$ 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.

$ 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

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:

$ skyvern skill copy -o .codex/skills/

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

JSON output

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

$ # 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

Command not found: skyvern

Make sure the package is installed and on your PATH:

$ pip install skyvern
$ which skyvern

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

$ python3 -m skyvern --help

Authentication errors

Verify your API key is set:

$ echo $SKYVERN_API_KEY

You can also pass it directly:

$ skyvern credentials add --api-key YOUR_KEY

Get an API key from Settings in the Skyvern dashboard.

No active browser session

Browser commands require an active session. Create one first:

$ skyvern browser session create

Or specify a session explicitly:

$ skyvern browser navigate --url https://example.com --session pbs_xxx