@pen.dev/cli 0.2.8

package/LICENSE

@@ -0,0 +1,66 @@
+Pencil CLI — Proprietary Software License
+
+Copyright (c) 2026 High Agency, Inc. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of High Agency, Inc. ("Licensor").
+
+1. LICENSE GRANT
+
+   Subject to the terms of this License, Licensor grants you a limited,
+   non-exclusive, non-transferable, non-sublicensable, revocable license to
+   install and use the Software solely in connection with the Pencil platform
+   and services provided by Licensor.
+
+2. RESTRICTIONS
+
+   You may not, and may not permit others to:
+
+   (a) modify, adapt, translate, or create derivative works of the Software;
+   (b) reverse engineer, decompile, disassemble, or otherwise attempt to
+       derive the source code of the Software;
+   (c) redistribute, sublicense, lease, rent, loan, or otherwise transfer
+       the Software to any third party;
+   (d) use the Software to build or operate a product or service that
+       competes with Pencil or the Licensor's offerings;
+   (e) remove or alter any proprietary notices, labels, or marks on the
+       Software.
+
+3. OWNERSHIP
+
+   The Software is licensed, not sold. Licensor retains all right, title,
+   and interest in and to the Software, including all intellectual property
+   rights therein.
+
+4. TERMINATION
+
+   This License is effective until terminated. It will terminate automatically
+   if you fail to comply with any of its terms. Licensor may also terminate
+   this License at any time for any reason. Upon termination you must cease
+   all use of the Software and destroy all copies.
+
+5. DISCLAIMER OF WARRANTIES
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. LICENSOR DOES NOT
+   WARRANT THAT THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE.
+
+6. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR
+   REVENUE, WHETHER INCURRED DIRECTLY OR INDIRECTLY, ARISING OUT OF YOUR
+   USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF LICENSOR HAS BEEN
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. GENERAL
+
+   This License constitutes the entire agreement between you and Licensor
+   regarding the Software and supersedes all prior agreements. This License
+   shall be governed by and construed in accordance with the laws of the
+   State of Delaware, United States, without regard to its conflict of law
+   provisions. If any provision of this License is held to be unenforceable,
+   the remaining provisions shall remain in full force and effect.
+
+   For questions about this License, contact: hq@pencil.dev

package/README.md

@@ -0,0 +1,369 @@
+# pen.dev CLI (formerly Pencil CLI)
+
+Command-line interface for [pen.dev](https://pen.dev) — create and edit `.pen` design files from the terminal. 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. Built on the same editor engine as the desktop app and IDE extension, with full headless rendering, AI image generation, and stock photo support.
+
+## Installation
+
+```bash
+npm install -g @pen.dev/cli
+# or
+pnpm add -g @pen.dev/cli
+# or
+yarn global add @pen.dev/cli
+```
+
+## Authentication
+
+The CLI requires authentication before running agent operations. There are two methods:
+
+### Sign Up
+
+```bash
+pen signup --email you@example.com --username johndoe --name "John Doe"
+```
+
+Creates a new account. You'll receive a verification email — click the link, then log in.
+
+### Interactive Login
+
+```bash
+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`.
+
+### Non-Interactive Login
+
+```bash
+# Step 1: Request an OTP code
+pen login --email you@example.com
+
+# Step 2: Log in with the code from your email
+pen login --email you@example.com --code 123456
+```
+
+When flags are provided the interactive prompts are skipped, useful for scripting and CI.
+
+### CLI Key (for CI/CD)
+
+Set the `PEN_CLI_KEY` environment variable. CLI keys are scoped to an organization and can be created/revoked in the **Developer Keys** section of your organization settings on the pen.dev web app.
+
+```bash
+PEN_CLI_KEY=pencil_cli_... pen --out design.pen --prompt "Create a form" --agent claude
+```
+
+The CLI key always takes precedence over a stored session token.
+
+### Checking Status
+
+```bash
+pen status
+```
+
+Displays the current authentication method, verifies the session with the backend, and shows account details (email, name, organization for CLI keys).
+
+## Quick Start
+
+```bash
+# 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" --agent claude
+
+# Modify an existing design
+pen --in existing.pen --out modified.pen --prompt "Add a blue submit button" --agent claude
+
+# Start an interactive shell (in headless mode)
+pen interactive -o design.pen
+
+# Start an interactive shell (connect to a running pen.dev app)
+pen interactive -a desktop -i design.pen
+
+# List available models
+pen --list-models --agent claude
+```
+
+## Usage
+
+```
+pen [command] [options]
+
+Commands:
+  signup                 Create a new account (flags required, see below)
+  login                  Log in interactively (email + password or OTP)
+  status                 Check authentication status
+  version                Show CLI version
+  interactive            Start an interactive tool shell (see below)
+
+Options:
+  --in, -i <path>        Input .pen file (optional, starts with empty canvas if omitted)
+  --out, -o <path>       Output .pen file path (required unless --export is used)
+  --prompt, -p <text>    Prompt for the AI agent (required)
+  --prompt-file, -f <path>  Attach a file to send with the prompt (repeatable). Images (png, jpeg, gif, webp) or text files; paths are not the prompt text itself.
+  --agent <type>         Agent to use when --model is omitted: claude, codex, gemini (default: claude)
+  --model, -m <id>       Model to use; agent is inferred from the model id
+  --custom, -c           Use custom Claude model config (e.g. AWS Bedrock, Vertex AI)
+  --list-models          List available models and exit
+  --tasks, -t <path>     JSON tasks file for batch operations
+  --workspace, -w <path> Workspace folder path to run the agent in
+  --export, -e <path>    Export an image of the final result
+  --export-scale <n>     Export scale factor (default: 1)
+  --export-type <type>   Export format: png, jpeg, webp, pdf (default: png)
+  --verbose-mcp          Log full MCP tool error details to the console
+  --help, -h             Show help message
+```
+
+## 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.
+
+```
+pen interactive [options]
+
+Options:
+  --app, -a <name>   Connect to a running pen.dev app (e.g. desktop, vscode)
+  --in, -i <path>    Input .pen file (optional, empty canvas if omitted)
+  --out, -o <path>   Output .pen file (required in headless mode)
+  --help, -h         Show detailed tool reference. Important for agentic workflows, so agents can learn the tool.
+```
+
+### Modes
+
+**App mode** — connects to a running pen.dev desktop or extension. Changes are applied live.
+
+```bash
+pen interactive -a desktop -i my-design.pen
+```
+
+**Headless mode** — spins up a local editor without a GUI. Use `save()` to write to `--out`.
+
+```bash
+# New empty canvas saved to the output file
+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
+save()                      Save the document to disk (headless) or app
+exit()                      Exit the shell
+```
+
+### Getting started
+
+Begin with `get_editor_state` to load the schema and understand the document:
+
+```
+pen > get_editor_state({ include_schema: true })
+pen > batch_get()                                     # list top-level nodes
+pen > batch_get({ patterns: [{ reusable: true }] })   # find components
+```
+
+### Example
+
+```
+pen > get_editor_state({ include_schema: true })
+pen > get_guidelines()
+pen > get_guidelines({ category: "guide", name: "Landing Page" })
+pen > batch_design({ input: 'rect=Insert(document,{type:"rectangle",name:"Foo",x:10,y:10,width:300,height:200,fill:"#E5484D"})' })
+pen > get_screenshot({ nodeId: "hero" })
+pen > save()
+pen > exit()
+```
+
+Run `pen interactive --help` for the full tool reference with parameter types and descriptions.
+
+## Available Models
+
+```bash
+pen --list-models --agent claude|gemini|codex
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PEN_CLI_KEY` | CLI API key for CI/CD (takes precedence over stored session) |
+| `PEN_AGENT_API_KEY` | API key for the selected agent. |
+| `ANTHROPIC_API_KEY` | Anthropic API key for Claude agents. Ignored for Codex and Gemini. |
+| `PEN_API_BASE` | Backend API base URL (default: `https://api.pen.dev`) |
+| `DEBUG` | Enable debug logging |
+
+Further environment variables and agent config can be set in `settings.json`
+as well.
+
+## Supported Operations
+
+The CLI supports the following MCP tools with full feature parity to the desktop app:
+
+### Design Operations
+
+| Tool | Description |
+|------|-------------|
+| `batch_design` | Insert, Update, Delete, Move, Copy, Replace, SetVariables, Generate, FindEmptySpace |
+| `batch_get` | Search and read nodes by pattern or ID |
+| `get_variables` | Read design variables |
+| `get_editor_state` | Get document metadata and structure |
+| `snapshot_layout` | Get document structure with computed bounds |
+
+### Visual Operations (headless rendering via CanvasKit)
+
+| Tool | Description |
+|------|-------------|
+| `get_screenshot` | Render a node to PNG image |
+| `export_nodes` | Export nodes to images in PNG/JPEG/WEBP/PDF formats |
+
+### Image Generation
+
+The `batch_design` `Generate()` operation supports both AI-generated and stock images. Generated images are saved to an `images/` directory alongside the output `.pen` file.
+
+| Type | Description |
+|------|-------------|
+| `G(nodeId, "ai", prompt)` | AI-generated image from a text prompt |
+| `G(nodeId, "stock", keywords)` | Stock photo from Unsplash |
+
+### Guidelines
+
+| Tool | Description |
+|------|-------------|
+| `get_guidelines` | Load guides and styles for working with .pen files |
+
+## Examples
+
+### Create a Login Page
+
+```bash
+pen --out login.pen --agent claude --prompt "Create a modern login page with:
+- Email input field
+- Password input field
+- 'Sign In' button
+- 'Forgot password?' link
+- Social login options (Google, GitHub)"
+```
+
+### Add Components to Existing Design
+
+```bash
+pen --in dashboard.pen --out dashboard-v2.pen --agent gemini --prompt "Add a sidebar navigation with:
+- Dashboard link (active)
+- Users link
+- Settings link
+- Logout button at bottom"
+```
+
+### Create a Component Library
+
+```bash
+pen --out components.pen --agent codex --prompt "Create a component library with:
+- Primary, secondary, and ghost button variants
+- Text input with label and error state
+- Card component with header and content
+- Badge component in success, warning, error colors"
+```
+
+### Using a Specific Model
+
+Use `--model` to select a different Claude model:
+
+```bash
+# Use Claude Opus for complex tasks requiring highest capability
+pen --out complex-app.pen \
+  --model claude-opus-4-6 \
+  --prompt "Create a complete e-commerce product page with image gallery,
+reviews section, related products, and add-to-cart functionality"
+
+# Use Claude Haiku for simple, fast tasks
+pen --out simple.pen \
+  --model claude-haiku-4-5 \
+  --prompt "Create a simple 404 error page"
+```
+
+### CI/CD Usage
+
+```bash
+# Authenticate with a CLI key
+export PEN_CLI_KEY=pencil_cli_...
+export PEN_AGENT_API_KEY=sk-...
+
+# Generate designs in a pipeline
+pen --out onboarding.pen --prompt "Create a 3-step onboarding flow" --agent claude
+```
+
+### Verbose MCP Error Logging
+
+Use `--verbose-mcp` to show full MCP tool error details (including stack traces where available) in the CLI output when a tool fails:
+
+```bash
+pen --out debug.pen \
+  --agent claude \
+  --prompt "Create a simple layout" \
+  --verbose-mcp
+```
+
+### Batch Processing with Tasks File
+
+Use `--tasks` to process multiple designs from a JSON tasks file:
+
+```bash
+pen --tasks batch-tasks.json --agent claude
+```
+
+Example `batch-tasks.json`:
+
+```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"
+    },
+    {
+      "out": "from-reference.pen",
+      "prompt": "Match the layout and palette of the attached reference",
+      "promptFiles": ["./assets/reference.png"]
+    }
+  ]
+}
+```
+
+Each task in the array supports the same options as CLI arguments:
+- `in` - Input file (optional)
+- `out` - Output file (required)
+- `prompt` - AI prompt (required)
+- `model` - Model override (optional)
+- `promptFiles` - Array of attachment paths (optional). Relative paths are resolved from the directory that contains the tasks JSON file.
+
+## Limitations
+
+The CLI is designed for headless operation and has some limitations compared to the desktop app:
+
+- **No real-time preview** - Changes are saved to file, not displayed interactively
+- **No interactive UI features** - No selection, zoom, or pan controls
+- **No library browsing** - Cannot browse or import from `.pen` libraries
+
+## Token Storage
+
+| File | Purpose |
+|------|---------|
+| `~/.pencil/session-cli.json` | Stored session token from `pen login` |
+
+The CLI uses a separate session file from the desktop app (`~/.pencil/session-desktop.json`) so the backend can distinguish which client is in use.
+
+## License
+
+Proprietary — see LICENSE file. © High Agency, Inc.

package/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: pen-design
+description: >
+  Create high-quality visual designs — websites, app screens, dashboards, slides, marketing materials, social media graphics — using the pen.dev CLI tool. Use this skill whenever the user wants to create, generate, or visualize any kind of UI design, mockup, wireframe, layout, webpage, app screen, presentation slide, poster, banner, or marketing asset. Also use it when the user says things like "design me a...", "make a visual for...", "create a mockup of...", "what would X look like?", or wants to turn an idea into a visual. Even if the user doesn't mention "pen.dev" or "design tool" explicitly — if they want something visual created, this is the skill to use.
+---
+
+# pen.dev Design
+
+Create professional visual designs from natural language descriptions using the pen.dev CLI. pen.dev is a headless design tool that generates `.pen` files (a structured JSON design format) and can export them as images.
+
+## Setup
+
+Before designing, make sure the pen.dev CLI is available.
+
+### Check installation
+
+```bash
+which pen || npx pen version
+```
+
+If `pen` is not found, install it:
+
+```bash
+npm install -g @pen.dev/cli
+```
+
+If global install fails due to permissions, install locally instead:
+
+```bash
+npm install @pen.dev/cli
+```
+
+Then run it via `npx pen` (or `./node_modules/.bin/pen`) instead of `pen`.
+You can learn about the available commands via the `pen --help` command.
+
+### Authentication
+
+#### pen.dev user
+
+To use the CLI, an authenticated user logged in to pen.dev is required. First, check
+the current user configuration on the machine with the `pen status` command.
+
+If not logged in, there are the following options:
+
+- use `pen signup --email you@example.com --username johndoe --name "John Doe"` command, to create a new user.
+- use `pen login --email you@example.com [--code abc123]` to authenticate an existing or newly created user.
+- optionally, the `PEN_CLI_KEY` env var can also be used for authentication if its set in your session.
+
+#### Claude Code agent
+
+The CLI needs auth to run its AI agent for which Claude Code is required. For that
+there needs to be an authenticated Claude Code user set in the system configuration
+either via env var or a user subscription.
+
+If none of these are available, tell the user what options they have and help them set one up.
+
+### Staying up to date
+
+This skill stays in sync with the **pen.dev CLI npm package** (`@pen.dev/cli`). The published package includes `SKILL.md` at its root; the package version is the skill version.
+
+**Check for a newer CLI / skill**
+
+- Latest version on the registry: `npm view @pen.dev/cli version`
+- Installed CLI: `pen version`, or `npm list -g @pen.dev/cli` (global) / `npm list @pen.dev/cli` (project)
+
+**Upgrade the CLI**, then refresh your copied skill file (agents do not auto-update skill files you placed in config folders):
+
+```bash
+npm install -g @pen.dev/cli
+```
+
+**Where to copy the skill from after installing**
+
+- From a dependency tree: `node_modules/@pen.dev/cli/SKILL.md` (path is the same for global and local installs; resolve from your project root or global `node_modules` prefix).
+
+**Fetch the same file without cloning the repo** (mirrors the npm tarball; optional third-party CDNs):
+
+- `https://unpkg.com/@pen.dev/cli@latest/SKILL.md`
+- `https://cdn.jsdelivr.net/npm/@pen.dev/cli@latest/SKILL.md`
+
+Use `@latest` for the newest publish, or pin (e.g. `@0.2.4`) for a reproducible snapshot.
+
+**If you don’t know where skills live on this machine**
+
+Agents don’t always get the skills directory from context. When the path isn’t obvious:
+
+- **Ask the user** where their agent or IDE loads skills from, or where they want this skill installed.
+- **Check the product’s docs** for “skills”, “agent skills”, or “plugins” — paths differ by tool and version.
+- You can still **use the skill content without installing**: fetch or open the **`SKILL.md` URL above** (unpkg/jsDelivr) in the session so guidance applies even when the on-disk path is unknown. For a persistent install, copy the fetched file into the path the user or docs specify.
+
+**Typical skill locations** (confirm with your tool’s current docs — layouts change):
+
+| Environment | Where to put `SKILL.md` |
+|-------------|-------------------------|
+| **Cursor** | Project: `.cursor/skills/pen-design/SKILL.md`; user-level: under `~/.cursor/skills/` |
+| **Claude Code** | Often `.claude/skills/pen-design/SKILL.md` or user-level under `~/.claude/` |
+| **OpenClaw** | Often `~/.openclaw/skills/`, workspace `.agents/skills/`, or paths in [OpenClaw skills docs](https://docs.openclaw.ai/skills/) — verify for the user’s setup |
+| **Other agents (Codex, etc.)** | Use the directory your product uses for skills or prompts |
+
+Example (adjust the destination path to match your agent):
+
+```bash
+curl -fsSL "https://unpkg.com/@pen.dev/cli@latest/SKILL.md" -o .cursor/skills/pen-design/SKILL.md
+```
+
+**When to check for an update**
+
+- **Early in the session**, before the first pen.dev design run (compare `npm view @pen.dev/cli version` to the installed CLI), so you aren’t following stale instructions.
+- **Again** if the user says they upgraded the CLI, or if behavior doesn’t match this doc (flags, auth, timing).
+- **Not** before every single command — once per session is enough unless something changed or errors suggest a version mismatch.
+
+## Creating a Design
+
+The core command:
+
+```bash
+pen --out <output.pen> --prompt "<design description>" --export <output.png> --export-scale 2
+```
+
+Key flags:
+- `--out, -o` — where to save the `.pen` file (required)
+- `--prompt, -p` — what to design (required)
+- `--prompt-file, -f` — attach an image or text file to send with the prompt (repeatable). Same idea as attaching reference images in the pen.dev editor chat; not for loading the prompt text from a file.
+- `--export, -e` — export an image of the result
+- `--export-scale` — image resolution multiplier (use 2 for crisp output)
+- `--export-type` — format: `png` (default), `jpeg`, `webp`, `pdf`
+- `--in, -i` — start from an existing `.pen` file (for iteration)
+- `--model, -m` — Claude model to use (defaults to Opus)
+
+### Passing the Prompt
+
+Pass the user's request directly as the prompt — do not expand, or add detail beyond what the user actually said. The pen.dev CLI has its own AI designer agent that handles creative decisions like layout structure, color palettes, typography, spacing, and content. Adding your own design specifics on top of the user's request will conflict with the CLI agent's own judgment and produce worse results.
+
+If the user says "make me a landing page for a coffee shop", the prompt should be exactly that — not a paragraph with hero sections, color palettes, and font choices you invented.
+
+### Timing Expectations
+
+Design generation is not instant — the CLI runs an AI agent that plans the layout, creates each element, and validates the result visually. Expect:
+
+- **Simple designs** (a card, a single component): 1-2 minutes
+- **Medium designs** (an app screen, a landing page section): 2-3 minutes
+- **Complex designs** (full landing page, detailed dashboard): 3-5+ minutes
+
+Let the user know upfront that generation will take a few minutes so they're not left wondering. Use a generous timeout (at least 600000ms / 10 minutes) when running the command.
+
+### Showing the Result
+
+After the command completes, read the exported image to show it to the user:
+
+```bash
+# The command exports to the path you specified
+pen --out design.pen --prompt "..." --export design.png --export-scale 2
+```
+
+Then use the Read tool on the exported PNG — it will render visually since you're a multimodal model.
+
+Always show the image to the user after creating it. This is the whole point — they want to see the visual.
+
+## Iterating on a Design
+
+When the user wants changes to an existing design, use the `--in` flag to load the previous `.pen` file:
+
+```bash
+pen --in design.pen --out design-v2.pen --prompt "Make the header larger and change the accent color to green" --export design-v2.png --export-scale 2
+```
+
+The agent will read the existing design and apply modifications rather than starting from scratch.
+
+For quick successive iterations, keep a consistent naming pattern:
+- `design.pen` → `design-v2.pen` → `design-v3.pen`
+- Or use a single file: `--in design.pen --out design.pen` (overwrites)
+
+## Working Directory
+
+Save design files in the user's current working directory or a subdirectory like `designs/`. Don't use temp directories — the user will want to find and iterate on these files later.