# The CoPage CLI > The CoPage CLI (copage) is a free, single-file program that lets you and your coding agent make architecture, cloud, network and flow diagrams on your own computer, with no account. Diagrams stay in your project, and SVG or PNG exports carry the diagram inside, so they open for editing again. 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](/docs/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](/docs/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](#the-copage-app)). ## Install macOS and Linux: ```bash curl -fsSL https://copage.semerjyan.dev/install.sh | sh ``` Windows (PowerShell): ```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 ```bash 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: ```bash 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](/docs/agents). ## Commands ```bash 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 ` writes `.svg`, `.png`, `.drawio` or `.json`, picked by the file's extension. | Option | What it does | | --- | --- | | `--width ` | PNG width (default: twice the diagram's size) | | `--once` | Write the file once; don't keep it up to date | | `--forget` | Stop keeping this file (or, with no file, all of the diagram's files) up to date | 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 ` 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 ` 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 ` runs another pack and `--rules a,b` runs single checks; `copage rules` lists them. | Exit status | Meaning | | --- | --- | | 0 | Every check passed | | 1 | A check found something | | 2 | A check couldn't run (not a pass) | 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](/docs/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 (CoPage app, early access) The CLI needs no account. If you also use the CoPage app (decks, comments, a team), sign in from the terminal: ```bash 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: ```bash copage diagram upload checkout-1a2b # or --all; prints the link in CoPage copage diagram download # 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 ` 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](/#early-access). ## Updates ```bash 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 --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/`, where `` 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. ## Questions ### Is the CoPage CLI free? Yes. The CLI is free, needs no account and runs on your computer. Decks and team features are in the CoPage app, which is in early access. ### Does the CoPage CLI send my diagrams anywhere? No. Diagrams stay in your project's `.copage` folder. The CLI goes online only when you ask: to install or update, to sign in, and, once signed in, to copy a diagram to or from the CoPage app or work on documents there. ### Which coding agents work with the CoPage CLI? Claude Code, Codex, Cursor and GitHub Copilot in VS Code. `copage skill install` teaches them the CLI; `copage connect claude|cursor|vscode|codex` adds the local MCP server `copage-local` instead. ### Can I edit an exported SVG or PNG again? Yes. SVG and PNG files exported by the CLI carry the diagram inside. `copage diagram open docs/architecture.svg` opens it in the editor, and the file is rewritten when you change the diagram. ### Can I use CoPage diagram checks in CI? Yes. `copage diagram check ` exits with 0 when every check passes, 1 when a check found something and 2 when a check couldn't run.