The CoPage CLI

The CoPage CLI is one program for diagrams. Your coding agent (Claude Code, Codex, Cursor, GitHub Copilot) draws them from the command line, you adjust them in an editor that opens in your browser, and both of you export them as SVG or PNG for your docs. It runs on your computer: no account, and your diagrams stay in your project.

• AWS, Azure, Google Cloud and general icons built in (more than 3,500), offline. See Diagrams.
• The agent sees what it drew (render) and is told what's messy (check: loose connectors, unlabelled icons, stacked shapes), so it can fix it before you look. See Checks.
• Exported SVG and PNG files carry the diagram inside (without its comments and notes): open the picture again to edit it. Files you export are kept up to date when the diagram changes.
• Imports and exports draw.io files, and reads draw.io's own PNG and SVG exports.

The CLI does diagrams only. Decks (presentations) live in the CoPage app, which is in early access; signed in, the CLI can work on them there (see The CoPage app).

#Install

macOS and Linux:

curl -fsSL https://copage.semerjyan.dev/install.sh | sh

Windows (PowerShell):

irm https://copage.semerjyan.dev/install.ps1 | iex

The scripts put copage in ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\copage); set COPAGE_INSTALL_DIR to choose another folder. No admin rights are needed. Builds exist for macOS (Apple silicon and Intel), Linux (x86-64) and Windows (x86-64).

Rendering and PNG/SVG export use Chrome, Edge, Chromium or Brave installed on the computer (Edge comes with Windows). Export to .drawio or .json needs no browser.

#Start in a project

cd my-project
copage init                 # keeps diagrams in ./.copage (commit it)
copage skill install        # teaches your coding agent to use copage

Then ask your agent: "Draw our checkout architecture on AWS and put it in docs/architecture.svg".

copage skill install writes the skill for Claude Code (.claude/skills) and for Codex, Cursor and others (.agents/skills). Add --global to install it in your home folder for every project.

Agents that prefer MCP can use copage connect instead of the skill:

copage connect claude       # or cursor | vscode | codex | all

This adds an MCP server named copage-local to the agent's user settings. The CoPage app's own server is named copage, so an agent can have both and knows which diagrams are on this computer. --print shows the configuration instead of writing it. Details: Connect AI agents.

#Commands

copage open                                   # the editor, in your browser
copage diagram new "Checkout" --ops ops.json  # create (ops: see `copage guide`)
copage diagram list                           # your diagrams
copage diagram show checkout-1a2b             # an outline with element ids (--json for the full document)
copage diagram apply checkout-1a2b ops.json   # edit: all ops apply, or none
copage diagram render checkout-1a2b           # PNG to look at; prints its path
copage diagram check checkout-1a2b            # tidiness checks
copage diagram export checkout-1a2b docs/checkout.svg   # and kept up to date from now on
copage diagram open docs/checkout.svg         # edit the picture again
copage diagram import old.drawio              # bring in draw.io diagrams
copage diagram delete checkout-1a2b           # moves it to .copage/trash
copage assets load balancer --collection aws  # find icons
copage guide                                  # the full reference for agents (ops, element fields, icons)
copage stop                                   # stop the background editor

copage diagram has the short alias copage d. Ops files can also come from stdin (-).

copage open shows your diagrams and three examples (AWS, Azure, Google Cloud); opening an example copies it into your diagrams. Until your agent has the skill or the MCP server, the editor offers to connect one.

#Export for docs

copage diagram export <id> <file> writes .svg, .png, .drawio or .json, picked by the file's extension.

An exported SVG or PNG is remembered in .copage/exports.json and rewritten when the diagram changes while the editor runs (copage open). With no file, copage diagram export <id> rewrites the remembered ones. copage diagram open docs/checkout.svg opens the picture for editing: it's the same diagram, or a new one if the file came from someone else.

#Checks and exit codes

copage diagram check <id> runs the "Diagram essentials" pack by default: connectors attached at both ends, every icon labelled, nothing stacked or left unconnected, no leftover placeholder text. --ruleset <pack> runs another pack and --rules a,b runs single checks; copage rules lists them.

Scripts and CI can rely on these. AI checks (personal data, tone and the like) would send the diagram's text to an AI model, so the CLI leaves them out: they run in the CoPage app. A pack skips them; one you name with --rules counts as a check that couldn't run. More in Checks.

#Where things are

• .copage/diagrams/*.json: the diagrams (commit these).
• .copage/exports.json: which files each diagram is exported to (commit it too).
• .copage/config.json: project settings, such as "cloud": false (commit it).
• .copage/cloud.json: which diagrams were copied to or from the CoPage app (yours only, git-ignored).
• .copage/.gitignore keeps working files (history, renders, the editor's state) out of git.
• Without a project (no copage init in this folder or above it), diagrams go to ~/.copage.

#The CoPage app App · early access

The CLI needs no account. If you also use the CoPage app (decks, comments, a team), sign in from the terminal:

copage auth login     # opens the app in your browser: check the code, pick a workspace, allow
copage auth status    # who this computer is signed in as
copage auth logout    # revoke this computer's key and forget it

Signing in sends no diagrams anywhere. The CLI gets an API key named after the computer, listed in the app under Account → AI agents, where you can revoke it. It is kept in ~/.config/copage/credentials.json (Windows: %APPDATA%\copage), readable only by you and never in a project. In CI, set COPAGE_TOKEN to a key instead.

Copying between this computer and your workspace is always a command, and a copy, never a sync:

copage diagram upload checkout-1a2b   # or --all; prints the link in CoPage
copage diagram download <link>        # a diagram from CoPage into this project

Images go along; comments stay where they were written. Uploading again updates the copy. If someone changed it in the app since, the upload stops: --replace overwrites it (the app keeps their version in its history), --as-new makes another copy. For a project that must never go to the cloud, copage init --local-only writes "cloud": false to .copage/config.json, and uploads from it are refused for everyone.

Signed in, the CLI also works on documents in the app: --cloud on copage diagram list, new, show, apply, render, check and open (or a diagram's link instead of its id), and copage deck list|new|show|apply|render|check|comments|open for decks, which live only in the app. copage skill list, copage skill show <id|name> and copage skill save SKILL.md read and save your workspace's skills (its guidance for agents).

The CoPage app is in early access: request access.

#Updates

copage update               # download the newest release and replace this one
copage update --auto on     # look for new releases once a day (off unless you turn it on)

The download is checked against its SHA-256 before it replaces the program. With --auto on, a newer release is mentioned in one line after a command you run in a terminal; never for agents, in CI, or with COPAGE_NO_UPDATE_CHECK=1.

#On a work computer

The CoPage CLI needs no admin rights and no account. What IT may ask about:

• What it contacts. Nothing by itself: automatic update checks are off unless you turn them on. Installing and copage update fetch from copage.semerjyan.dev, and the file itself comes from a short-lived link on Amazon S3 (*.s3.eu-central-1.amazonaws.com). Signed in, the CLI also talks to the CoPage app over HTTPS only, when you run copage diagram upload|download, a --cloud command, copage deck or copage skill list|show|save, and when your agent uses the local MCP server's upload_to_cloud.
• Proxies. It uses the proxy set in Windows or macOS, or HTTPS_PROXY. Proxy auto-config (PAC) files aren't read, so set HTTPS_PROXY where they're used. A company certificate for HTTPS inspection works once it's installed on the computer.
• Your coding agent. The CLI sends a diagram to the CoPage app only when you copy it there. Your agent sends what it reads, diagrams included, to its own AI provider, as it does with your code.
• Keys. copage auth login keeps the app's key in ~/.config/copage/credentials.json (%APPDATA%\copage on Windows), and copage connect <agent> --cloud writes one into that agent's settings; both readable by you only. Revoke them in the app under Account → AI agents.
• Allow-listing. Computers that run only approved programs (AppLocker or App Control on Windows, Santa on macOS) block the CLI until IT allows it.
• Installing without a script. Download https://copage.semerjyan.dev/cli/download/latest/<target>, where <target> is aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu or x86_64-pc-windows-msvc. Compare its SHA-256 with the same link plus .sha256, unpack it and put copage (copage.exe) in a folder on your PATH. On macOS, a file your browser downloaded needs xattr -d com.apple.quarantine copage once.
• Rendering. copage diagram render and PNG/SVG exports run Chrome or Edge without a window (headless mode). Where IT turned that off (Edge's HeadlessModeEnabled policy), they fail with a message saying so: set COPAGE_CHROME to another Chrome, Chromium or Brave, or export .drawio or .json. The editor works in any browser.