Skip to main content
The moda CLI is the primary way to give an agent Moda. Any harness with a shell — Claude Code, Codex, Cursor, Cowork, your own scripts — drives Moda the same way, with no per-editor configuration: the CLI is the integration. Requirements: macOS or Linux (x64 or arm64), Node.js and npm on your PATH, and a Moda account. Windows works too, in beta — see below.

​
Install

Install the CLI

Sign in

Opens your browser and mints a scoped key into your OS keychain. No credential is ever printed.

Add the skills

Teaches your agent how Moda expects to be driven — the design workflow, not just the verb list. See Skills.

Check it worked

Connectivity, credential validity, scopes, version range, keychain health — all in one command.
Prefer plugin-managed skills in Claude Code? /plugin marketplace add moda-design/moda, then /plugin install moda@moda. Steps 1 and 2 still apply — the plugin carries the skills, not the CLI.

​
Or let your agent do it

Paste this into Claude Code, Codex, or any shell-capable agent and it will run the whole thing:

​
Your first canvas

The shortest real path is to ask for something you actually want — “make a one-pager from this README”, “turn these notes into a deck” — and let the skills drive. Under the hood, that is this loop:

Create the canvas

Prints the canvas id (cvs_…) and its editor URL. The category sets the page size and the export defaults: slides, social, carousel, pdf (a Document canvas in the app), diagram, ui, animation, prints, or web-ads.

Author it

Read the canvas to get its page ids and a revision token, then apply markup to a page:
moda docs markup prints the full markup reference offline. For fine-grained changes to an existing design, moda canvas edit runs a sandboxed JS edit batch instead.

Look at it

Authoring is a loop — mutate, render, inspect, repair. Agents that skip the render step ship broken layouts.
Then look at the PNG. moda canvas markup and moda canvas edit also take --screenshot <path>, which captures the page they just touched in the same command.

Deliver

Every canvas stays fully editable in Moda afterwards — the CLI never produces a dead artifact.

​
The verb surface

moda describe prints machine-readable schemas for every verb, with mutating / destructive / metered markers, so an agent can introspect the CLI instead of guessing. A selection: Conventions worth knowing:
  • --json is for agents. Compact JSON on stdout, --pretty when a human is reading. The envelope is additive-only: keys are never renamed or removed, so parse defensively and ignore what you do not recognize.
  • Metered verbs announce themselves. Anything that spends credits prints its cost class before and a receipt after. moda account costs lists what is metered, straight from the server.
  • moda last-error re-prints the full error envelope of the last failed command — no re-run needed.
  • moda docs markup | edit | workflow prints the offline reference texts.

​
Auth in CI and headless environments

No verb ever prints a credential. moda auth status shows identity, org, plan, and scopes — never the key.

​
Windows

npm i -g @moda-design/moda works on Windows too — it pulls the platform binary automatically, and the CLI is identical. Treat it as beta: it is built and tested on windows-latest in CI, but it has not been soaked in real use. Two differences worth knowing — config lives in %APPDATA%\moda and state in %LOCALAPPDATA%\moda, and there is no Windows keychain backend, so the credential sits in %APPDATA%\moda\credentials.json behind your user-profile ACL rather than in a keychain (moda auth login says so once). If it misbehaves: WSL2 runs the Linux build unchanged, and the Moda connector installs nothing at all.

​
Updating

The CLI and the skills update separately:
The CLI prints a once-daily notice on stderr when a newer version exists. The server also enforces a minimum supported version, so a very old CLI is told to update rather than failing mysteriously.