# Deploying a Widget to Modyo

Deployment is **not an MCP operation**. The MCP's widget flow ends at validation (`widgets-validate`) plus a served smoke test (`npm run dev`). Getting the widget onto a Modyo site happens outside the MCP, through one of two paths:

1. **CI from the widget's repository (the standard path).** `widgets-scaffold` initializes the project as a git repository with an initial commit precisely to enable this: the developer pushes the repo to their forge, and a CI workflow runs `@modyo/cli push` with credentials from the repo's CI secrets. Every deploy is traceable to a commit.
2. **Manual push (the explicit developer path).** The developer runs `modyo-cli push` in their own shell, inside the widget directory. This is a legitimate development-time operation — frequent and forgiving; a wrong widget is overwritten by the next push.

**The agent never pushes.** There is no MCP tool for it, and the agent must not route around that by running the CLI itself: the MCP process never reads `MODYO_TOKEN` or the widget's `.env`/`.modyo` files, and token material never enters the chat. If the operator asks the agent to deploy, the answer is to point at these two paths.

## Required credentials variables

`@modyo/cli push` needs, via env vars (CI secrets) or a credentials file (`.env` or `.modyo`, sibling of `package.json`):

| Variable | Required | Description |
|----------|----------|-------------|
| `MODYO_ACCOUNT_URL` | yes | Your Modyo account URL, e.g. `https://acme.modyo.com` |
| `MODYO_TOKEN` | yes | API token generated at Modyo admin → Settings → API Access |
| `MODYO_SITE_HOST` | **one of** | Host (slug) of the target site |
| `MODYO_SITE_ID` | **one of** | Numeric id of the target site |

Set **exactly one** of `MODYO_SITE_HOST` or `MODYO_SITE_ID` — not both. The Modyo CLI accepts either, but rejects having both at once.

The canonical template ships an `.env.example` with the same keys and empty values — copy and fill in for local use; in CI, export them as secrets instead.

## File precedence: `.modyo` over `.env`

When both files exist, the CLI reads `.modyo` and ignores `.env`. The files are NOT merged — pick one and commit to it.

This behaviour was verified against `@modyo/cli` 3.6.2 (`src/push/merge-env-variables.ts`: `if (existsSync(modyoEnvPath)) { ... } else if (existsSync(dotEnvPath)) { ... }` — mutually exclusive branches). The MCP no longer pins a CLI version — deployment happens outside the MCP — so re-check this if you are on a newer CLI. As of that version, the `.env` fallback also triggers a deprecation warning ("`.env` file is deprecated and will be removed in future versions"), and the CLI accepts `MODYO_*` vars straight from `process.env` when neither file is present — that is what CI environments use.

## Draft vs publish

`@modyo/cli push` uploads the widget to Modyo as a **draft**. The operator publishes from the admin UI when ready.

This separation is deliberate:
- Push is a development-time operation. Frequent and forgiving — if the widget is wrong, the next push overwrites it.
- Publish is an operator-time decision. Affects production users. Requires human review.

For automated end-to-end publishing, the CLI offers `push:publish` — a decision for the repo's CI workflow, never the agent.

## Troubleshooting the CLI

Common `@modyo/cli push` error patterns:

| stderr pattern | Likely cause / fix |
|----------------|--------------------|
| `Unauthorized`, `401`, `Invalid token` | `MODYO_TOKEN` invalid. Regenerate it from Modyo admin → Settings → API Access, and update the CI secret or credentials file. |
| `Site not found`, `404` | `MODYO_SITE_HOST` not found. Verify the host exists in the Modyo account and that the token has permission for that site. |
| `ECONNREFUSED`, `ENOTFOUND`, `network`, `getaddrinfo` | Network error reaching Modyo. Verify `MODYO_ACCOUNT_URL` points to a reachable host. |

## Credentials policy (for the agent)

- **`MODYO_TOKEN` never enters the chat.** Do not read it — from `.env`, `.modyo`, or the shell environment — into your own context for any purpose.
- **Do not call the Modyo CLI or the admin API with the operator's token.** Deploy questions get answered with the two paths above, not with an execution.
- **Do not resolve the target site yourself.** If the operator's config is ambiguous (both `MODYO_SITE_HOST` and `MODYO_SITE_ID`, or neither), say so and let them fix the config.