Pencil CLI

The Pencil 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 — no GUI required.

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

Installation

npm install -g @pencil.dev/cli

Verify the installation:

pencil version

Authentication

The CLI requires authentication before running agent operations. There are two methods.

Interactive Login

pencil 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 PENCIL_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 Pencil web app.

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

Checking Status

pencil status

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

Quick Start

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

Commands

pencil login

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

pencil status

Check authentication status and display account details.

pencil version

Print the installed CLI version.

pencil interactive

Start an interactive tool shell. See Interactive Mode below.

Agent Mode

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

pencil [options]

Examples

Create a new design:

pencil --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:

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

Use a specific model:

# Use Claude Haiku for simple, fast tasks
pencil --out simple.pen \
  --model claude-haiku-4-5 \
  --prompt "Create a simple 404 error page"

Export to image:

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

Available Models

List available models at any time with:

pencil --list-models

Interactive Mode

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

pencil interactive [options]

App Mode

Connects to a running Pencil desktop app or extension via WebSocket. Changes are applied live.

pencil 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
pencil interactive -o output.pen
 
# Edit an existing file
pencil 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

pencil > get_editor_state({ include_schema: true })
pencil > get_guidelines()
pencil > get_guidelines({ category: "guide", name: "Landing Page" })
pencil > batch_design({ operations: 'hero=I(document,{type:"frame",name:"Hero",x:0,y:0,width:1440,height:900,fill:"#0A0A0A"})' })
pencil > get_screenshot({ nodeId: "hero" })
pencil > save()
pencil > exit()

Batch Processing

Use --tasks to process multiple designs from a JSON file. Tasks run sequentially — each one gets its own editor instance.

pencil --tasks batch.json

Example batch.json:

{
  "tasks": [
    {
      "out": "landing-page.pen",
      "prompt": "Create a SaaS landing page with hero, features, and pricing sections"
    },
    {
      "in": "existing-app.pen",
      "out": "existing-app-v2.pen",
      "prompt": "Add a dark mode toggle to the header"
    },
    {
      "out": "mobile-menu.pen",
      "model": "claude-haiku-4-5",
      "prompt": "Create a mobile hamburger menu component"
    }
  ]
}

Each task supports:

Supported MCP Tools

The CLI supports the same MCP tools as the desktop app and IDE extension.

Design Operations

Visual Operations

Image Generation

The batch_design G() operation supports both AI-generated and stock images:

Style & Guidelines

CI/CD Usage

Use a CLI key and Anthropic API key to run Pencil in automated pipelines.

export PENCIL_CLI_KEY=pencil_cli_...
export ANTHROPIC_API_KEY=sk-ant-...
 
pencil --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.