Pencil CLI

The Pencil CLI is an experimental feature built into the desktop application. It lets you run Pencil from your terminal to perform batch operations, automate repetitive design tasks, and build custom AI-powered workflows on top of your design files.

Experimental: The CLI is under heavy development. Commands, flags, and config formats may change between releases. Use with caution in production pipelines.

Installation

The CLI ships with the Pencil desktop app — no separate download required. To make the pencil command available in your terminal, open the desktop app and navigate to:

File → Install pencil command into PATH

This adds the pencil binary to your system PATH. You may need to restart your terminal session for the change to take effect.

Usage

The primary way to use the CLI is through an agent configuration file that describes one or more tasks to execute:

pencil --agent-config config.json

Agent Configuration

The agent config file is a JSON array of task objects. Each task describes a single operation to perform on a design file. The supported fields are:

  • file — Path to the .pen file to operate on
  • prompt — Natural-language instruction describing what the AI should do
  • model — AI model to use for the task (e.g. "claude-4")
  • attachments — Optional array of file paths for reference images, specs, or other context

Example Configuration

[
  {
    "file": "./designs/landing-page.pen",
    "prompt": "Redesign the hero section with a gradient background and centered CTA button",
    "model": "claude-4",
    "attachments": [
      "./references/hero-inspiration.png"
    ]
  },
  {
    "file": "./designs/dashboard.pen",
    "prompt": "Add a sidebar navigation with icons for Home, Analytics, Settings, and Profile",
    "model": "claude-4"
  },
  {
    "file": "./designs/components.pen",
    "prompt": "Create dark mode variants for all button components",
    "model": "claude-4",
    "attachments": [
      "./specs/dark-mode-colors.json"
    ]
  }
]

Limitations

Keep these constraints in mind when building workflows:

  • The CLI requires the Pencil desktop app to be installed. It communicates with the app's rendering engine under the hood.
  • The CLI cannot auto-create .pen files. Target files must already exist before running a task.
  • The feature is under heavy development — expect breaking changes, incomplete error messages, and evolving configuration schemas.

Upcoming

The team is working on a headless CLI version that will be distributed as a standalone npm package:

npm install -g @pencil/cli
  • No desktop app dependency — runs entirely in the terminal or CI/CD pipelines
  • Minimal footprint — lightweight package without the full editor runtime
  • Server-side optimized — designed for headless environments, Docker containers, and cloud functions

The headless CLI will support the same agent configuration format, making migration seamless when it ships.

Last updated: February 22, 2026