CLI Reference

Complete Gencow CLI command reference — all commands, flags, and environment variables

Quick Start

gencow <command> [options]

Use bunx gencow@latest <command> for the recommended zero-install runner. Node.js users can run the same commands with npx gencow@latest <command>. Both forms resolve the registry's latest tag and reuse a matching cached package when possible; registry metadata caching can briefly delay a release appearing immediately after publication. Plain gencow may instead run the version pinned in the current project or another installed binary on PATH. The examples below omit the runner for readability.

Project Commands

gencow init

Create a new Gencow project, install dependencies, and run codegen (including gencow/schema-auth.ts and gencow/generated/db-schema.gen.ts).

gencow init my-app
gencow init .                    # current directory
gencow init my-app -t fullstack  # with template
gencow init . --force            # non-empty directory
gencow init my-app --no-install  # scaffold without installing dependencies

Use gencow init . --force to add Gencow to an existing non-Gencow project. Do not run it inside a project cloned from gencow templates clone; cloned templates already include their backend and config files.

gencow add

Add AI components to your project.

gencow add AI
gencow add sso
gencow add AI RAG Reranker
gencow add Guardrails Prompts

Available components: Agent, AI, Guardrails, Memory, Parsers, Prompts, RAG, Reranker, Search, SSO, Tools, and TossPayments. Analytics is listed as coming soon and cannot be installed yet.

Dependencies are auto-resolved (e.g., gencow add RAG also installs AI). gencow add sso currently generates Google login only, backed by Better Auth socialProviders.google. gencow add SSO and legacy gencow add OAuth are accepted as aliases, but docs and CLI output use lowercase gencow add sso.

gencow codegen

Generate frontend API client without starting the dev server.

gencow codegen
gencow codegen --outdir src/gencow/

gencow doctor

Analyze the project without deploying it. Doctor reports backend/schema diagnostics plus a secret-free migration preview: schema source, Drizzle Kit version, observed history format/count, and the expected admission decision.

gencow doctor
gencow doctor --plan
gencow doctor --diff
gencow doctor --fix

The preview only observes source and migration structure. It does not parse tenant SQL semantics or replace canonical gencow db:generate validation.

Commands (Login Required)

gencow templates

Browse, clone, download, and publish marketplace templates.

gencow templates list
gencow templates info <slug>
gencow templates clone <slug> [dir]
gencow templates clone <slug> [dir] --version <version>
gencow templates download <slug> --out template.tar.gz
gencow templates publish --title "CRM Starter" --price 29

clone extracts the template source into a new local directory. After cloning, install dependencies, log in, and deploy from the cloned project:

cd my-app
bun install
gencow login
gencow deploy

For fullstack templates with a built frontend:

bun run build
gencow deploy --static dist/

Template clone does not include gencow.json, .env, .gencow/, platform tokens, or preview app bindings. The first deploy creates a new app ID for your account.

gencow login

Authenticate via browser (Device Auth flow).

gencow login
# → Opens browser for authentication
# → Saves token to ~/.gencow/credentials.json

gencow logout

Clear saved credentials.

gencow logout

gencow whoami

Show current user info and token status.

gencow whoami
# Email:    [email protected]
# User ID:  user_...
# Platform: https://gencow.app
# Token:    gk_1234567...abcd
# Expires:  ...

gencow dev

Start cloud development with hot-reload. Watches for file changes, auto-deploys to cloud, and streams live logs.

gencow dev             # Cloud development (default)
gencow dev --local     # Local Bun + Hono + PGlite development
gencow dev --verbose   # Show all HTTP logs

What it does:

• Auto-deploys code to Gencow Cloud on file changes
• Streams live server logs to your terminal
• Auto-generates gencow/api.ts and gencow/README.md
• Syncs schema with database via auto-migration

gencow db:push

Generate versioned Drizzle migration SQL from schema.ts, upload the migration bundle, and apply only the pending plan to the cloud database.

gencow db:push           # Push to dev cloud DB (default)
gencow db:push --prod    # Push to production DB (confirmation required)
gencow db:push --existing-bundle # Apply committed migrations without regeneration
gencow db:push --status <receipt> # Inspect an exact push receipt without applying DDL
gencow db:push --json    # Stable JSON result for automation or coding agents

If a migration is blocked, the CLI reports who must act, whether the database changed, whether retry is safe, the pending migration and statement location, a stable reason code, suggested fixes, forbidden actions, and the next command. The platform does not echo raw SQL. The CLI shows project-relative local context only after the local file hash matches the server-audited hash, and it redacts SQL literals and executable bodies.

The bundle records the generator name and version for audit, but the platform does not admit or reject SQL based on a Drizzle Kit version allowlist. Admission is determined by the migration protocol, ordered SQL hashes, ledger consistency, protected platform boundaries, and transactional postconditions. Ordinary tenant DROP/ALTER risk is returned as a non-blocking warning.

For execution failures, databaseState: "ROLLED_BACK" means PostgreSQL and the exact journal prove that the transaction did not commit. Do not infer retry safety from that field alone: follow retryPolicy and nextAction. If a connection closes at the commit boundary, the platform checks the journal before responding; a proven commit is treated as applied and the same immutable bundle becomes an idempotent no-op.

--json emits exactly one versioned JSON object for success, cancellation, local preflight/generation failures, authentication failures, network failures, and server diagnostics. A real Drizzle generation error stops before bundle upload; only an explicit no-change result continues with the existing pending bundle.

Do not use --force, edit the migration journal, or modify an already-applied migration to work around a failure. RECOVERY_REQUIRED is reserved for an operation that started migration execution but whose final journal state cannot be proven; verify the remote migration state before retrying. Preflight service failures remain UNCHANGED and are assigned to the platform rather than asking you to rewrite valid SQL.

The responsibility boundary is: Drizzle Kit generates versioned SQL, Gencow verifies the immutable app/database plan, Drizzle ORM executes pending migrations, and PostgreSQL decides SQL, constraint, transaction, and catalog results. See Database Migrations for the full model.

gencow db:check

Build and inspect the committed cloud migration plan without running Drizzle Kit, writing project files, applying DDL, writing the migration journal, or promoting staged source.

gencow db:check           # Check the DEV cloud plan
gencow db:check --prod    # Check the Production cloud plan
gencow db:check --inspect-state # Read-only platform state inspection
gencow db:check --json    # Stable JSON result for automation

db:check is a read-only manifest, history, pending-plan, and policy preflight. Successful JSON output reports both projectState: "UNCHANGED" and databaseState: "UNCHANGED". If a new app has no tenant database yet, the plan also reports databaseBootstrapRequired: true; this is a normal passing state and does not create the database. The result may include non-blocking warnings for data loss, locks, or rollout compatibility. db:push and backend deploy print the user-owned SQL review/recovery notice before sending a mutation request; automatic backups are best-effort and no new approval flag is required. It does not execute the SQL in a temporary PostgreSQL database, so it does not prove live-data compatibility, lock duration, or application behavior.

gencow db:generate

Generate SQL migration files from schema.ts changes. Runs automatically before gencow deploy — only needed if you want to preview or commit migrations separately.

gencow db:generate
# → Creates files in gencow/migrations/

gencow db:seed

Run gencow/seed.ts to insert test data.

gencow db:seed           # Seed dev cloud app (default)
gencow db:seed --prod    # Seed production app (confirmation required)

gencow db:reset and gencow db:restore

Manage local PGlite development data. These commands do not reset or restore a cloud database.

gencow db:reset --local # Back up local data, then reset it
gencow db:restore   # Restore the latest local backup

Run the local server with gencow dev --local when the command asks for it.

gencow static

Deploy static frontend files only (dist/, out/, build/).

gencow static              # Auto-detects dist/out/build/ → deploy to dev
gencow static dist/        # Specify static directory
gencow static --prod       # Deploy to production app
gencow static --app my-app dist/ # Target a specific app

When run from a frontend subdirectory, gencow static detects the parent backend root for app metadata. The static directory is still resolved relative to the frontend working directory.

The selected directory must contain a regular index.html file at its root. Gencow rejects an auto-detected compiler-only dist/ before creating a production target, deploying a fullstack backend, packaging static files, or making a static deployment request. The Platform verifies the archive again before changing deployment state and returns HTTP 400 with STATIC_SITE_ENTRYPOINT_REQUIRED for an invalid site artifact.

gencow deploy

Deploy backend to cloud. Defaults to dev environment. Use --prod for production on Startup / Enterprise. Automatically runs drizzle-kit generate before bundling.

Safe default for people and AI agents: If a request says only “deploy,” use the development command without --prod. Add --prod only when the user or operator explicitly asks for production, PROD, or the final production deployment. Do not treat a deploy token, CI context, --yes, or a generic “publish/release” request as permission to change production. Ask before proceeding when the target is ambiguous.

gencow deploy                # Deploy backend to dev
gencow deploy --static dist/ # Deploy backend, then static files
gencow deploy --prod         # Deploy backend to production (Startup / Enterprise)
gencow deploy --prod --region kr # First production app placement region
gencow deploy --rollback     # Roll back dev deployment
gencow deploy --rollback --prod  # Roll back production deployment
gencow deploy logs           # Follow server logs
gencow deploy status         # App status

Hobby plan: gencow deploy --prod is blocked for Hobby users. gencow deploy (dev) is available to all plans.

Auto-migration: Both gencow dev and gencow deploy automatically run bunx drizzle-kit generate before bundling. Interactive prompts (e.g., column renames) pass through to your terminal.

gencow backup

Manage cloud database backups for the selected app.

gencow backup list
gencow backup list --all
gencow backup create "before import"
gencow backup restore <id>
gencow backup restore-file <path>
gencow backup download <id>
gencow backup delete <id>

Restore and delete operations require confirmation. Backup availability, retention, and download capability depend on the app plan; see Cloud Plan Limits.

gencow logs

Read local development server logs. For cloud logs, use gencow deploy logs.

gencow logs
gencow logs --lines 100
gencow logs --follow
gencow deploy logs --prod

gencow jobs

Inspect cron jobs, scheduled tasks, execution history, and workflow runs.

gencow jobs
gencow jobs history --limit 50
gencow jobs workflow cancel wf_123
gencow jobs workflow delete wf_123 --yes
gencow jobs workflow cleanup --status terminal --older-than 7d
gencow jobs workflow cleanup --status terminal --older-than 7d --apply --yes

Workflow cleanup is a dry run unless --apply is provided. Add --prod to target the production app.

gencow env

Manage environment variables on your cloud app. For local development, keep frontend vars in root .env and backend vars in gencow/.env by default (or your configured envFile).

gencow env list              # List dev app env vars
gencow env list --prod       # List prod app env vars (Startup / Enterprise)
gencow env set KEY=VALUE     # Set dev env var (hot-reload, no restart)
gencow env set KEY=VALUE --prod  # Set prod env var (Startup / Enterprise)
gencow env unset KEY         # Remove env var
gencow env push              # Push backend env file to dev app
gencow env push --prod       # Push backend env production file to prod app
gencow env push --file ./config/backend.env  # Push an explicit backend env file

⚡ Changes apply instantly — no app restart needed.

gencow origins

Inspect the effective public origins used by API CORS and auth/OAuth flows.

gencow origins list                         # Show managed + code-declared origins
gencow origins check https://myapp.vercel.app
gencow origins list --prod                  # Production app (Startup / Enterprise)

Declare external frontend origins in gencow.config.js, then redeploy:

export default {
  frontendOrigins: ["https://myapp.vercel.app"],
};

gencow cors (legacy)

Inspect legacy cloud CORS overrides. Prefer gencow origins plus frontendOrigins for new apps.

gencow cors list                          # Show auto + custom origins
gencow origins check https://myapp.vercel.app
gencow cors list --prod                   # Production app (Startup / Enterprise)

*.gencow.app and localhost:* are allowed automatically. Custom domains connected with gencow domain set are same-origin, so they do not need app config. Legacy add/remove commands remain for old stored overrides but should not be used for new public origins.

gencow files

Manage uploaded files in your app's storage.

gencow files upload <path...>                 # Upload private files
gencow files upload hero.png --public         # Upload a public website asset
gencow files upload dir/ -r                   # Upload directory recursively
gencow files list                             # List uploaded files and visibility
gencow files visibility <storage_id> public   # Make a file public
gencow files visibility <storage_id> private  # Make a file private
gencow files delete <storage_id>              # Delete a file
gencow files url <storage_id>                 # Get public URL or short-lived private grant URL

Hosted storage is private by default. Use public visibility only for assets that anyone with the URL may read; private files are shown through short-lived read grant URLs.

gencow config

Manage app image processing configuration.

gencow config set image.maxWidth 1200   # Set Auto WebP max width (px, 0-10000)
gencow config set image.quality 85      # Set Auto WebP quality (0-100)
gencow config get                       # Show current image config
gencow config reset                     # Reset to tier defaults

gencow domain

Manage custom domains. Custom domain set/rebind is available on Startup and Enterprise plans. Hobby users can still check or remove an existing domain. See Hosting & Custom Domains for the Dashboard flow, DNS records, canonical www/apex behavior, and automatic TLS.

gencow domain set www.myapp.com          # Connect a www custom domain to dev app
gencow domain set www.myapp.com --prod   # Connect a www custom domain to production app
gencow domain set myapp.com --prod       # Connect apex domain with ALIAS/ANAME/CNAME flattening
gencow domain set myapp.com --prod --dry-run
gencow domain set myapp.com --prod --yes
gencow domain status                 # Check dev DNS/TLS status
gencow domain status --prod          # Check production DNS/TLS status
gencow domain remove                 # Disconnect dev domain
gencow domain remove --prod          # Disconnect production domain

www.* domains use the exact CNAME target printed by the CLI and remain canonical when connected directly. Apex and proxied domains also use the unique _gencow-verification TXT record printed by gencow domain set; Gencow stores only its hash, and the challenge expires after 24 hours. For a pending binding, run domain set again to rotate an expired challenge. Re-running it for the same active app is idempotent. Apex domains need provider-supported ALIAS/ANAME/CNAME flattening, or the stable edge IP fallback.

For Cloudflare, use DNS only or SSL/TLS mode Full (strict). Full is also supported, but Full (strict) is recommended. Flexible and Off are not supported because they send HTTP from Cloudflare to the Gencow origin. A Flexible request returns an HTTPS configuration page instead of serving the app or entering a redirect loop.

Domain status progresses through DNS verification and TLS preparation before becoming active. While a domain is pending, HTTP and app traffic fail closed. Once active, direct HTTP GET and HEAD requests redirect to the same HTTPS URL with status 308; unsafe HTTP methods are rejected.

Without --prod, domain commands target the dev app. Use --prod when the public domain should serve the production app listed in gencow.json as prodApp. If the same domain is already connected to the related dev app, preview with --dry-run and apply the move with --yes.

gencow app

Manage your cloud apps.

gencow app list          # List all your apps
gencow app create <name> # Create a new app
gencow app delete <name> # Delete an app (confirmation required)
gencow app status        # Show current app status

memory_exceeded apps are shown as memory exceeded. gencow app status <name> includes the status reason, recent OOM count, last OOM time, and recovery guidance.

The --prod Flag

Most cloud commands support --prod to target the production app instead of the dev app. This reads the prodApp field from gencow.json.

--prod is an explicit production boundary, not a stronger version of the default command. During development, omit it. Automation and coding agents must use it only after an explicit production request, because it can create or modify a separate live app and database. Existing credentials and noninteractive flags do not replace that instruction.

# Database
gencow db:push --prod
gencow db:seed --prod    # confirmation required

# Static deploy
gencow static --prod

# Environment
gencow env list --prod
gencow env set KEY=VALUE --prod
gencow env push --prod

# Files & Config
gencow files list --prod
gencow config get --prod

# Domains
gencow domain set myapp.com --prod
gencow domain status --prod
gencow domain remove --prod

Production apps are created automatically when you first run gencow deploy --prod.

Environment Variables

Next Steps

• Client SDK — Typed defs, auth, realtime
• React Hooks — useQuery, useMutation, provider
• Core API — Backend API