pen.dev CLI

The pen.dev CLI is a standalone command-line tool for creating and editing .pen design files from the terminal. It runs the same editor engine as the desktop app and IDE extension, fully headless and without a GUI.

Use it to run the AI agent with a prompt, call MCP tools directly in an interactive shell, or export to PNG/JPEG/WEBP/PDF.

Installation

npm install -g @pen.dev/cli

Verify the installation:

pen version

Authentication

The CLI requires authentication for agent operations, exports, interactive mode, and workspace access. There are two methods.

Interactive Login

pen login

This starts an interactive session where you choose your login method (email + password or email + OTP code). On success the session token is stored in ~/.pencil/session-cli.json.

CLI Key (for CI/CD)

Set the PEN_CLI_KEY environment variable. CLI keys are scoped to an organization and can be created in the Developer Keys section of your organization settings on the pen.dev web app.

PEN_CLI_KEY=pencil_cli_... pen --out design.pen --prompt "Create a form"

Checking Status

pen status

Displays the current authentication method, verifies the session with the backend, and shows account details.

Quick Start

# Log in first
pen login
 
# Create a new design from scratch
pen --out design.pen --prompt "Create a login page with email and password fields"
 
# Modify an existing design
pen --in existing.pen --out modified.pen --prompt "Add a blue submit button"
 
# Export a design to PNG
pen --in design.pen --export design.png
 
# Start an interactive shell
pen interactive -o design.pen
 
# List available models
pen --list-models

Commands

pen login

Log in interactively via email + password or email + OTP.

pen status

Check authentication status and display account details.

pen codex-login

Sign in to OpenAI Codex with a ChatGPT Plus/Pro account (browser or device-code flow). Required before using --agent codex or a gpt-* model without an API key.

pen codex-logout

Remove the stored OpenAI Codex credential.

pen version

Print the installed CLI version.

pen interactive

Start an interactive tool shell. See Interactive Mode below.

Agent Mode

Run the AI agent with a prompt to create or modify designs.

pen [options]

Examples

Create a new design:

pen --out login.pen --prompt "Create a modern login page with:
- Email input field
- Password input field
- Sign In button
- Forgot password link
- Social login options (Google, GitHub)"

Modify an existing design:

pen --in dashboard.pen --out dashboard-v2.pen --prompt "Add a sidebar navigation with:
- Dashboard link (active)
- Users link
- Settings link
- Logout button at bottom"

Export to image:

pen --in design.pen --export hero.png --export-scale 2

Available Models

List the models available for each agent:

pen --list-models --agent claude
pen --list-models --agent codex
pen --list-models --agent gemini

Pass one of the returned model IDs to --model.

Interactive Mode

The interactive shell lets you call MCP tools directly on .pen files. It is useful for scripting, debugging, and agentic workflows that need fine-grained control over design operations.

pen interactive [options]

App Mode

Connects to a running pen.dev app. Changes are applied live.

pen interactive -a desktop -i my-design.pen

Headless Mode

Spins up a local editor without a GUI. Use save() to write to the output file.

# New empty canvas
pen interactive -o output.pen
 
# Edit an existing file
pen interactive -i input.pen -o output.pen

Shell Commands

tool_name({ key: value })   Call an MCP tool with arguments
tool_name()                 Call an MCP tool with no arguments
save()                      Save the document to disk
exit()                      Exit the shell

Example Session

pen > read_skill()
pen > read_skill({ path: "pen-schema.md" })
pen > read_skill({ path: "execute.md" })
pen > get_app_state()
pen > get_style()
pen > execute({ input: 'hero=Insert(document,{type:"frame",name:"Hero",x:0,y:0,width:1440,height:900})' })
pen > execute({ input: 'TakeScreenshot([hero])' })
pen > save()
pen > exit()

Supported MCP Tools

The CLI exposes these MCP tools by default:

Design Operations

Visual Operations

Screenshots are taken with the execute TakeScreenshot() operation. Files are exported with the execute Export() operation, which supports PNG/JPEG/WEBP/PDF images and HTML output.

Style & Guidelines

The browser tool is also available when the MCP server targets the desktop app. spawn_agents is available only when the server starts with -enable_spawn_agents.

CI/CD Usage

For a Claude run in CI/CD, set a CLI key and Anthropic API key.

export PEN_CLI_KEY=pencil_cli_...
export ANTHROPIC_API_KEY=sk-ant-...
 
pen --out onboarding.pen --prompt "Create a 3-step onboarding flow"

Environment Variables

Token Storage

The CLI uses a separate session file from the desktop app so the backend can distinguish which client is in use.