Propagate CLI

The propagate CLI lives in the propagate monorepo. It is the sole interface for deploying app stacks — the previous Next.js wizard has been removed.

Prerequisites

Install

From the propagate repo root:

pnpm install
pnpm build

Run via:

pnpm propagate <command>
# or
node packages/cli/dist/index.js <command>

Commands

Quick start

# 1. Initialise workspace in your project directory
propagate init
 
# 2. Authenticate (opens browser — connect Cardano wallet, sign nonce)
propagate login
 
# 3. Interactive manifest generation
propagate create
# Prompts: client name, event name/dates, event code, GitHub org,
#          Vercel team, app selection, timelining secrets (Telegram, OpenAI), Vercel token
#          Redis and Neo4j are provisioned on apply unless overridden in values.yaml
#          then GitHub App install in browser (if not already installed)
 
# 4. Validate (requires app.manifest.yaml in each selected app repo)
propagate validate
 
# 5. Provision
export PROPAGATE_HOST_NAME=prisma.events   # optional
propagate apply --yes
 
# 6. Check outputs
propagate status

Workspace layout

Running commands from a project directory creates:

.propagate/
  stack.yaml          # infrastructure intent (committed)
  values.yaml         # user secrets — gitignored
  credentials.json    # GitHub App install + Vercel token — gitignored
  resolved.json       # validation output — gitignored
  pulumi-state/       # local Pulumi backend — gitignored
  last-applied/       # snapshot after successful apply — gitignored

propagate create prompts

The create flow mirrors the former web wizard steps:

1. Metadata — client name, event name, start/end dates
2. Event code — DNS-safe slug (default derived from event name, e.g. Argentina ALJ → argentina-alj)
3. GitHub — target organisation
4. Vercel — team ID
5. App selection — multi-select from deployable catalog (docs, timelining)
6. User capabilities — conditional prompts (e.g. TELEGRAM_BOT_TOKEN, OPENAI_API_KEY for timelining). Redis and Neo4j are not prompted — provisioned on apply.
7. Vercel token — stored in credentials.json
8. GitHub App install — browser opens on propagate.prisma.events ; install the Propagate app on the target org (skipped if already installed)

Authentication

Wallet login

propagate login opens a browser session on the hosted auth app (propagate.prisma.events ). You connect a Cardano wallet, sign a nonce, and the CLI polls until complete. The session is stored at ~/.propagate/session.json. Authorization is checked against register.prisma.events  (enrol app) — your wallet must be registered there.

Override the auth host for local dev:

PROPAGATE_AUTH_URL=http://localhost:3000 propagate login

Local dev requires REGISTER_API_TOKEN in packages/web/.env.local on the auth server.

GitHub App install

Forking requires the Propagate GitHub App installed on provider.github.targetOrg — not a personal access token. Triggered during propagate create, before propagate apply (if missing), via propagate auth github, or optionally after propagate login when a workspace stack already exists.

1. CLI creates an install session via POST /api/github/cli/init
2. Browser opens /cli-github-install
3. You install the app on the target GitHub organisation
4. GitHub redirects to the app Setup URL; CLI polls until complete
5. .propagate/credentials.json stores installationId, targetOrg, and credentialRef
6. At apply / destroy, the CLI mints a short-lived installation token from the auth server

Example credentials.json:

{
  "github": {
    "installationId": 12345678,
    "targetOrg": "client-org",
    "credentialRef": "...",
    "installedAt": "2026-06-13T..."
  },
  "vercelToken": "..."
}

Vercel token

For CI or headless use, the Vercel token can be supplied via environment variable instead of credentials.json:

export VERCEL_TOKEN=...

Vercel connect troubleshooting

Git-linked deploys require three links: Vercel OAuth (token + team), the Vercel GitHub App  on your target org, and GitHub under Vercel team → Settings → Integrations → GitHub → Connect.

If propagate auth vercel completes OAuth and GitHub App steps but fails verification:

1. In the Vercel dashboard for the stack’s team (stack.yaml → provider.vercel.teamId): Settings → Integrations → GitHub → Connect
2. Re-run propagate auth vercel or propagate apply (apply runs a live probe before Pulumi)

Monorepo packages

Related

• Manifests — stack.yaml and app.manifest.yaml schemas
• Workflow — full operator sequence
• Neo4j provisioning — Railway Neo4j for timelining