Skip to main content
Moda is a design tool you can drive: real editable decks, one-pagers, social posts, diagrams, websites and video on a live canvas — not flat images. Written to you, the agent. Do as much as you can without asking. Two things need the user: signing in, and — if you have no shell — the connector setup in step 5, which you guide rather than perform.

​
1. Pick your path

Can you run shell commands with internet access?
  • No → step 5.
  • Yes → step 2. The CLI is faster, cheaper in context, and can read this machine’s files. Two exceptions, in order:
    • You already know sign-in cannot finish here — no browser the user will see, and no MODA_API_KEY set. Go to step 5 now rather than installing something you will not be able to authenticate.
    • Unless there is no human present at all. Then stay on step 2: the connector needs someone to click through it, and step 3 names what the operator sets instead.
A sandboxed code interpreter usually cannot reach the network, so the install fails and nothing you do there helps the user. If you cannot tell, step 2 will tell you. Decide by what you can do, not by what you are called. Do not look for your own name in a list.

​
2. Ask Moda what is missing

Run moda doctor --json. It works before you have signed in, and one JSON object describes the whole install. If the command is not found:
  • A 401 or registry error means a private registry is shadowing the package. Retry with --registry https://registry.npmjs.org.
  • The install times out, or npm cannot reach the registry at all: you are in a sandbox with no network. Stop and go to step 5. Do not retry, and do not ask the user to run the command for you — the connector is the path that works from where you are.
  • Installed but not on PATH: use npx @moda-design/moda everywhere below.
  • Never sudo, and never pipe curl to a shell.
Installing is allowed only here. Once the skills exist their own Step 0 governs: a stale CLI you refresh with moda update, but a missing one you stop and hand to the user.

​
3. Fix only what doctor reports

moda auth login opens the user’s browser and stores a scoped key. Tell the user to finish signing in, then wait for the command to return — do not kill it while it waits.
  • No browser on this machine: the user runs moda auth login --paste and pastes the key themselves. You do not read it, relay it, or type it for them.
  • CI, or no human present: an operator sets MODA_API_KEY out of band, before you run. It is not something to ask anyone for.
Never ask for, print, echo, or store a key yourself. That rule outranks both fallbacks above: if the only way forward is a credential passing through you, stop — use the connector in step 5 instead. Signing up is free and needs no card.

​
4. Re-run doctor until every state holds

skills.installed must be one or more. Repeat step 3 until all four hold. Do not use the top-level ok field to decide this. It is doctor’s exit status: true on a machine with no credential and no skills, and false when a saved key was rejected or the network is unreachable. It is never a readiness signal. If a command fails, moda last-error prints the full envelope. Once you are signed in, moda ask "<question>" is free and answers with the exact commands — it needs a credential, so it cannot help you before the login in step 3. Tell the user Moda is ready, then go to step 6.

​
5. No shell? Use the connector

Ask the user to add a custom MCP connector with this server URL, then sign in when prompted:
In ChatGPT they must first turn on developer mode: Settings → Security and login → Developer mode. Two things stall here more than anything else, and only the user can do them:
  • If their account has more than one workspace, sign-in asks which one this connection acts in. With one workspace the question never appears.
  • Some hosts also need the connector switched on per conversation — a + or / menu, under Connectors. If moda_bootstrap is not among your tools, that is almost always why.
Setup is done when moda_bootstrap returns. Do not say it is connected before that.

​
6. Now make something

Setup is finished. This is first use, not part of it — if this step fails, do not reinstall or re-authenticate. Moda is already working. Tell the user what you can do now, then wait for them:
I can use Moda to design anything — slides, one-pagers, social posts, graphics and more. I can also set up your brand kit to start.
The skills carry the method — installed on this machine if you came through step 2, served by the connector if you came through step 5, where you fetch one with load_skill and it never arrives unless you ask. Follow them.