DocsCLI

The CLI

Capture screenshots directly from your terminal. Run any preset created on the dashboard — the CLI launches a local browser and executes the opcode program deterministically.

Quick start

Get up and running in one command:

macOS / Linux

Shell

curl -fsSL https://autokap.app/install.sh | sh

Windows (PowerShell)

Shell

irm https://autokap.app/install.ps1 | iex

Or use npx for a zero-install setup:

Shell

npx autokap@latest init

Install

Install it globally via npm:

Shell

npm install -g autokap

Authenticate

Shell

autokap login <your-cli-key>

Your key is stored locally in ~/.autokap/config.json. You only need to do this once.

One-step setup

Combine login and skill installation in a single command:

Shell

npx autokap@latest init --cli-key <your-cli-key> --agent claude

This authenticates your CLI and installs the AI agent skill into your project.

Run a preset

Run any preset created on the dashboard. The CLI fetches the opcode program and executes it locally — navigating, clicking, and capturing deterministically:

Shell

autokap run <preset-id>

Commands

Command	Description
autokap init	Set up AutoKap: authenticate and install the AI skill in one step
autokap login <key>	Authenticate with your CLI key
autokap logout	Remove stored credentials
autokap whoami	Show the account linked to the current CLI key
autokap ping	Verify CLI connection and confirm the key is still valid
autokap run <preset-id>	Run a preset capture using local Playwright
autokap run <id> --headed	Show the browser window for debugging
autokap skill	Export the AI agent skill file for preset creation
autokap --version	Show the installed version

How it works

You run a preset by its ID. The CLI fetches the execution program from the AutoKap server and launches a local Playwright browser.
The CLI executes the opcode program locally — navigating pages, clicking elements, and taking screenshots across all configured variants (viewports, themes, languages). No server control at runtime.
Screenshots are uploaded to AutoKap for mockup rendering and post-processing. Results appear in your dashboard.

Troubleshooting

Common errors you may encounter when using the CLI, and how to fix them.

Connection

Error	Cause	Fix
connect ECONNREFUSED	The AutoKap server is not running or unreachable.	Check your internet connection. If the issue persists, the AutoKap server may be temporarily down — try again in a few minutes.
getaddrinfo ENOTFOUND	DNS resolution failed — wrong server URL.	Check ~/.autokap/config.json for a correct apiBaseUrl. Re-run autokap login if needed.

Authentication

Error	Cause	Fix
Invalid CLI key	The CLI key is missing, revoked, or malformed.	Generate a new CLI key in the dashboard and run autokap login '<'key'>'.
Not authenticated	No config file found at ~/.autokap/config.json.	Run autokap login '<'key'>' to authenticate.
CLI key not linked	This machine is not linked to your account with a valid stored CLI key.	Run autokap login '<'key'>' again or regenerate the CLI key from the dashboard if needed.

Version mismatch

Error	Cause	Fix
CLI is too old for this server	The server requires a newer protocol version.	Run npm install -g autokap@latest to update.

Preset & project

Error	Cause	Fix
Preset not found	The preset ID does not exist in the database.	Verify the ID in the dashboard — it may have been deleted.
Project not found	The project linked to the preset no longer exists.	Check the dashboard — the project may have been deleted.

Runtime

Error	Cause	Fix
timeout waiting for … (60000ms)	A browser command timed out.	Check that the local browser is responsive. Try --headed to debug visually.
Client disconnected	The CLI lost its connection to the server mid-capture.	Check network stability and re-run the preset.