> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.app/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Quickstart

> Install the moda CLI, sign in, and have your agent build its first canvas — three commands on any machine with a shell.

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](https://moda.app). Windows works too, in beta — see [below](#windows).

## Install

<Steps>
  <Step title="Install the CLI" icon="download">
    ```sh theme={null}
    npm i -g @moda-design/moda
    ```
  </Step>

  <Step title="Sign in" icon="key">
    Opens your browser and mints a scoped key into your OS keychain. No credential is ever printed.

    ```sh theme={null}
    moda auth login
    ```
  </Step>

  <Step title="Add the skills" icon="graduation-cap">
    Teaches your agent how Moda expects to be driven — the design workflow, not just the verb list. See
    [Skills](/agents/skills).

    ```sh theme={null}
    npx skills add moda-design/moda
    ```
  </Step>

  <Step title="Check it worked" icon="stethoscope">
    Connectivity, credential validity, scopes, version range, keychain health — all in one command.

    ```sh theme={null}
    moda doctor
    ```
  </Step>
</Steps>

<Tip>
  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.
</Tip>

### Or let your agent do it

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

```
Set up Moda for me so I can create designs, videos, decks, and documents from here.

1. Install the CLI: npm i -g @moda-design/moda
2. Authenticate: run `moda auth login` and wait for me to complete sign in.
3. Install the companion skills: run `npx skills add moda-design/moda`.
4. Verify: run `moda doctor` and tell me when everything is ready.
```

## 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:

<Steps>
  <Step title="Create the canvas" icon="plus">
    ```sh theme={null}
    moda canvas create --name "Launch one-pager" --category pdf
    ```

    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`.
  </Step>

  <Step title="Author it" icon="pen-ruler">
    Read the canvas to get its page ids and a revision token, then apply markup to a page:

    ```sh theme={null}
    CANVAS=cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV   # the id the previous step printed

    moda canvas read "$CANVAS" --summary
    moda canvas markup "$CANVAS" --page <page-id-from-read> --file one-pager.xml
    ```

    `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.
  </Step>

  <Step title="Look at it" icon="camera">
    Authoring is a loop — mutate, render, inspect, repair. Agents that skip the render step ship broken layouts.

    ```sh theme={null}
    moda canvas screenshot "$CANVAS" --output ./shots/
    ```

    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.
  </Step>

  <Step title="Deliver" icon="file-export">
    ```sh theme={null}
    moda export "$CANVAS" --format pdf --output ./one-pager.pdf
    moda canvas open "$CANVAS"
    ```
  </Step>
</Steps>

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:

| Group     | Verbs                                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| `auth`    | `login`, `logout`, `status`                                                                                |
| `canvas`  | `create`, `read`, `markup`, `edit`, `screenshot`, `add-pages`, `import-pptx`, `duplicate`, `share`, `open` |
| `export`  | `pdf`, `pptx`, `png`, `jpeg`, `mp4`, `gif` via `--format`                                                  |
| `brand`   | `list`, `show`, `pull`, `use`, `create`, `guides`                                                          |
| `media`   | `generate-image`, `edit-image`, `generate-video`, `upscale`, `remove-background`                           |
| `file`    | `upload`, `search`, `list`, `download`                                                                     |
| `drive`   | `tree`, `folders`, `mkdir`, `move`, `rename`, `rm`                                                         |
| `site`    | `create`, `set-content`, `publish`, `screenshot`                                                           |
| `task`    | `status`, `list`, `cancel`                                                                                 |
| `ask`     | [Ask Moda how to do something](/agents/ask-expert) — free and fast                                         |
| `account` | `status`, `usage`, `costs`                                                                                 |

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

| Situation                    | Do this                                                                             |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| Your laptop                  | `moda auth login` — browser flow, key lands in the OS keychain                      |
| SSH / container / no browser | `moda auth login --paste` — prints the mint URL, reads the key from a hidden prompt |
| CI, cron, scheduled jobs     | Set `MODA_API_KEY` to a scoped key from **Settings → Developer**                    |

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](/agents/mcp-connector) installs nothing
at all.

## Updating

The CLI and the skills update separately:

```sh theme={null}
npm i -g @moda-design/moda      # the CLI
npx skills add moda-design/moda # the skills (hash-pinned; never auto-update)
```

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.