<!-- zibby-template-version: 5 -->
# /zibby-deploy — deploy a Zibby workflow to the cloud

You are helping the user deploy a workflow they've been building locally.

> **⛔ Deploying an EXISTING catalog/marketplace agent (not one built here)?**
> STOP and read its `AGENT.md` FIRST — `zibby marketplace docs <slug>`. It is the
> agent's own runbook: the exact deploy command (incl. the REQUIRED
> `--agent <vendor>`), the stores it auto-provisions, the env/secrets to
> inject (`zibby agent env set` — NEVER in a prompt/trigger), the trigger
> INPUT shape, and how to verify. Do not guess these; the runbook is one
> command away. (The steps below are for deploying a workflow you built
> locally from source.)

## What `zibby agent deploy` does

1. Bundles the workflow's source (graph.mjs + nodes/ + package.json) into a tarball
2. Uploads it to S3 via a presigned URL
3. Triggers a remote build to install deps + bake the bundle
4. Registers the new bundle so future triggers run it

A successful deploy is required before `zibby agent trigger <uuid>` works against the cloud.

Canonical docs: **https://docs.zibby.app/workflows/deploying**

## Steps for this command

1. **Identify the workflow.** If the user passes a name, use it. Otherwise list everything under `paths.agents` (from `.zibby.config.mjs`) and ask.

2. **Pre-flight checks.** Read the workflow folder and confirm:
   - `graph.mjs` exists and exports a graph
   - `nodes/` has at least one node
   - `agent.json` is valid (must have `name`, `entryClass`, `triggers`)
   - `package.json` declares all imports used in nodes (run a quick grep to spot missing deps)

3. **Run the deploy:**
   ```
   zibby agent deploy <workflow-name>
   ```
   This is interactive if `--project` isn't passed. The user picks a project, the CLI handles auth via the saved session token.

4. **Watch the build.** The CLI streams the build output. If it succeeds, it prints the workflow's UUID. If it fails, the build logs show why — usually a missing dep in `package.json` or a syntax error in a node.

5. **Verify post-deploy:**
   ```
   zibby agent trigger <uuid> --input '{}'
   zibby agent logs <uuid> -t
   ```
   Tail logs until the workflow reaches `completed` (or `failed` — diagnose from logs).

## Common failure modes

- **Build fails with module-not-found** → node imports a package not in `package.json`. Add it and redeploy.
- **Build succeeds but trigger fails immediately** → `entryClass` in `agent.json` doesn't match a class exported by `graph.mjs`.
- **Workflow runs but a node fails** → tail the live logs and read the error. Most are in the agent's prompt/output handling.

## Optional flags worth knowing

`zibby agent deploy` accepts:
- `--project <id>` — skip the interactive project picker
- `--api-key <key>` — use a PAT instead of the session token (for CI)
- `--env <path>` — sync a `.env` file into per-workflow env vars after deploy. Repeatable; later files override.
- `--verbose` — print raw build output during the build (helpful for debugging build failures)

### Seeding per-workflow env on first deploy

If the workflow needs its own `ANTHROPIC_API_KEY`, `DATABASE_URL`, etc., put them in a `.env` and pass `--env`:

```
zibby agent deploy <name> --env .env
zibby agent deploy <name> --env .env --env .env.prod   # later files win
```

After deploy, manage them surgically with `zibby agent env set/unset/list/push <uuid>`. See `/zibby-list` to recover the UUID; full guide at https://docs.zibby.app/cloud/env-vars.

## Static outbound IP (dedicated egress)

If the user's workflow needs to call APIs that require IP allowlisting (corporate GitHub, GitLab Enterprise, paranoid SaaS firewalls), the workflow needs the **dedicated egress IP** addon. The flag lives on the legacy alias `zibby deploy` (NOT `zibby agent deploy`):

| Flag | What it does |
|------|-------------|
| `zibby deploy <name> --dedicated-ip status` | Show current addon state for the account (active / inactive / billing) |
| `zibby deploy <name> --dedicated-ip enable` | Enable the addon on the account (Pro subscription required, ~$50/mo). One-time per account. |
| `zibby deploy <name> --dedicated-ip use` | Mark THIS workflow as using the static egress IP (per-workflow opt-in, after `enable`) |
| `zibby deploy <name> --dedicated-ip unuse` | Stop routing this workflow through the static IP |
| `zibby deploy <name> --dedicated-ip disable` | Disable the addon for the whole account |

Typical first-time flow when the user says "I need a static outbound IP":
1. `zibby deploy <name> --dedicated-ip status` — check whether they have it
2. If inactive → `zibby deploy <name> --dedicated-ip enable` — enables the account-wide addon (interactive billing prompt; prerequisite Pro subscription)
3. `zibby deploy <name> --dedicated-ip use` — opts this specific workflow in
4. Regular `zibby agent deploy <name>` from now on uses the static IP

After `--dedicated-ip use`, every node in this workflow gets its outbound HTTP routed through the egress proxy, and `process.env.HTTP_PROXY` / `HTTPS_PROXY` are set in the sandbox automatically. Their static IPs are visible to customers via `https://docs.zibby.app/workflows/egress`.

**Don't** run `--dedicated-ip enable` without confirming with the user — it has billing impact ($50/mo addon). Always confirm. See `/zibby-static-ip` for the deeper walkthrough.