CLI & Skills

The skyvern CLI gives you direct access to browser automation, agent 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

Set your API key:

export SKYVERN_API_KEY="YOUR_KEY"  # get one at https://app.skyvern.com

Optionally run the interactive setup wizard to configure your environment:

skyvern init

Command reference

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.

Connect your local browser to Skyvern Cloud

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.

See the full guide for all options, manual tunnel setup, and security details.

Agents

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.

Agent 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 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                  # Register with Claude Desktop
skyvern setup cursor             # Register with Cursor
skyvern setup windsurf           # Register with Windsurf
skyvern setup openclaw           # Register with OpenClaw
skyvern setup opencode           # Register with OpenCode (API key auth; avoids OAuth timeouts)
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

For the local self-hosted path, skyvern quickstart or skyvern init can also configure Claude Code during the interactive MCP step. In a project directory that flow writes .mcp.json, installs .claude/skills/qa, and keeps the MCP connection fully local for localhost testing. skyvern mcp switch updates existing Skyvern entries in Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Hermes, and OpenClaw 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.

Other

skyvern docs                     # Open documentation in your browser
skyvern quickstart               # One-command setup + start
skyvern init                     # Interactive setup without starting services
skyvern init browser             # Initialize browser configuration only

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 reference markdown files that teach AI coding tools how to use Skyvern. They are not the same as MCP tools; they are documentation that an AI agent can load to learn the CLI and API.

skyvern skill list                  # List available skills
skyvern skill show skyvern          # Render a skill in the terminal
skyvern skill path skyvern          # Print the absolute path to a skill file
skyvern skill path                  # Print the skills directory
skyvern skill copy --output ./docs  # Copy all skills to a local directory
skyvern skill copy skyvern -o .     # Copy a single skill

Loading skills into AI tools

Skills are plain markdown files. You can load them into any AI coding tool that supports custom instructions:Claude Code: the recommended local path is skyvern quickstart or skyvern init, then choose Claude Code during MCP setup. That writes .mcp.json and installs bundled skills like /qa. You can also run skyvern setup claude-code later if you are configuring MCP separately.Codex: copy the skill into your project’s .codex/skills/ directory:

skyvern skill copy skyvern -o .codex/skills/

Hermes: copy the skill to your active Hermes profile’s skills directory. The skill needs Hermes-compatible frontmatter (metadata.hermes.requires_tools instead of allowed-tools):

# Create the skill directory
mkdir -p ~/.hermes/profiles/<your-profile>/skills/skyvern-browser-automation

# Copy the skill body (you'll need to replace the frontmatter; see below)
skyvern skill copy skyvern -o /tmp/skyvern-skill

Replace the frontmatter in the copied SKILL.md with:

---
name: skyvern-browser-automation
description: "Browser automation via Skyvern: scrape pages, fill forms, extract data, run workflows."
metadata:
  hermes:
    tags: [browser, automation, skyvern]
    requires_tools: [terminal]
---

Then move it into place: cp /tmp/skyvern-skill/SKILL.md ~/.hermes/profiles/<your-profile>/skills/skyvern-browser-automation/SKILL.mdVerify with hermes skills list | grep skyvern.

When both the Skyvern MCP server and the CLI skill are configured, Hermes prefers MCP tools over shelling out to the CLI, which is faster. The skill’s judgment procedure (task classification, step ordering) works with either execution path.

OpenClaw: copy the skill into your OpenClaw workspace skills/ directory. By default that workspace lives at ~/.openclaw/workspace/, but if you’ve customized the workspace path, use that location instead.

mkdir -p ~/.openclaw/workspace/skills
skyvern skill copy skyvern -o ~/.openclaw/workspace/skills/
openclaw skills list | grep skyvern

OpenClaw’s MCP config provides the callable Skyvern tools; the workspace skill is optional guidance that teaches the agent when to use them.

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

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

Getting Started

Core Features

Browser Automation

Agent Blocks

Handling Authentication

Optimization

Going to Production

Debugging

Self-Hosted Deployment

Install

Command reference

Services

Browser automation

Connect your local browser to Skyvern Cloud

Agents

Credentials

Agent blocks

MCP setup

Other

CLI vs MCP: when to use which

Skills

JSON output

Troubleshooting

​Install

​Command reference

​Services

​Browser automation

​Connect your local browser to Skyvern Cloud

​Agents

​Credentials

​Agent blocks

​MCP setup

​Other

​CLI vs MCP: when to use which

​Skills

​JSON output

​Troubleshooting

Install

Command reference

Services

Browser automation

Connect your local browser to Skyvern Cloud

Agents

Credentials

Agent blocks

MCP setup

Other

CLI vs MCP: when to use which

Skills

JSON output

Troubleshooting