Terminal
Terminal/Skill
Command reference for the Zuplo CLI, covering local dev, deploys, tests, environment variables, tunnels, and OpenAPI tools.
By Zuplo
Works with
npx skills add zuplo/tools --skill zuplo-cliThis skill helps developers use the Zuplo CLI to develop and manage their Zuplo API Gateway projects.
Use these sources in priority order:
node_modules/zuplo/docs/cli/ — version-matched, always available offline. Check both the project root and parent directories for monorepos.search-zuplo-docs and ask-question-about-zuplo if the Zuplo MCP server is connected.https://zuplo.com/docs/cli/overview or discover all pages at https://zuplo.com/docs/llms.txt.Use this skill when the user:
The Zuplo CLI requires Node.js 20+ (Node.js 22 recommended). The zuplo package is included as a dependency in Zuplo projects — there is no need to install it globally. Run CLI commands using your package manager's exec command:
npx zuplo <command> # npm
pnpx zuplo <command> # pnpm
Note: All
zuplocommands shown below should be run vianpx zuplo,pnpx zuplo, or equivalent. Thezuploprefix is shown withoutnpxfor brevity.
Two methods:
Uses device flow authentication — opens a browser for login and returns a refresh token for session persistence.
zuplo login
Pass via --api-key flag or ZUPLO_API_KEY environment variable:
export ZUPLO_API_KEY=zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx
API keys are scoped to an account. Get them from portal.zuplo.com > Settings > API Keys.
A Zuplo project has this layout:
my-api/
├── config/
│ ├── routes.oas.json # Route definitions (OpenAPI 3.1 format with x-zuplo-route extensions)
│ └── policies.json # Policy configuration (named policy instances)
├── modules/
│ └── my-handler.ts # Custom handlers and policies (TypeScript)
├── docs/ # Developer portal (optional, Zudoku-based)
│ └── zudoku.config.ts
├── tests/ # API test files (run with `zuplo test`)
├── zuplo.jsonc # Project config: version, compatibilityDate, projectType
├── package.json
├── .env # Local environment variables (do NOT commit)
└── .env.zuplo # Generated by `zuplo link` (do NOT commit)
config/routes.oas.json - OpenAPI 3.1 spec defining routes. Uses x-zuplo-route extension to attach handlers and policies. Multiple OpenAPI files are supported (processed alphabetically).config/policies.json - Defines named policy instances (type, handler module, options). Routes reference policies by name.zuplo.jsonc - Project-level config. projectType can be managed-edge, managed-dedicated, or self-hosted. compatibilityDate locks runtime behavior.modules/ - Custom TypeScript code referenced from config via $import(./modules/...) syntax..env - Local environment variables (not synced with remote). Format: KEY=VALUE per line..env.zuplo - Auto-generated by zuplo link. Contains account/project/environment info for connecting to Zuplo services locally.$import() syntaxJSON config files use $import() to reference code modules:
$import(@zuplo/runtime) - Built-in Zuplo modules$import(./modules/my-handler) - Custom modules in modules/ directoryzuplo devStart the local development server. Runs the API gateway, route designer (editor), and docs server.
zuplo dev # Default: API on :9000, editor on :9100, docs on :9200
zuplo dev --port 8080 # Custom API port
zuplo dev --no-start-editor # Skip the editor
zuplo dev --no-start-docs # Skip the docs server
zuplo dev --debug-port 9229 # Enable Chrome DevTools inspector
Ports:
To use Zuplo services (API keys, rate limiting) locally, first run zuplo link to connect to a remote environment.
zuplo editorStart just the OpenAPI Designer (route editor) standalone.
zuplo editor # Default port 9100
zuplo editor --port 8080 # Custom port
zuplo docsStart just the docs server standalone.
zuplo docs # Default port 9200
zuplo docs --port 3000 # Custom port
zuplo docs --server-url https://my-api.zuplo.dev # Point to remote API
zuplo docs --server-url http://localhost:9000 # Point to local API
zuplo linkLink a local directory to an existing Zuplo project. Creates .env.zuplo with account/project/environment info.
zuplo link # Interactive
zuplo link --account my-acct --project my-proj --environment my-env # Explicit
Use --no-fetch-environments to auto-detect environment from the git branch instead of fetching from Zuplo.
zuplo listList all deployed Zuplo APIs/environments.
zuplo list
zuplo list --account my-acct --project my-proj
zuplo project createCreate a new project in your account.
zuplo project create --name my-api-project
zuplo project create --name my-proj --account my-acct
zuplo deployDeploy the current directory. Uses the current git branch to select the environment by default — the default branch (typically main) maps to the production environment. In CI/CD, leave --environment unset so the branch being built selects the environment automatically. Only pass --environment when there is no git branch to detect (e.g. not in a git repo) or when you deliberately want to deploy to a specific named environment (e.g. deploying a tag to staging).
zuplo deploy # Uses git branch to select the environment
zuplo deploy --account my-acct --project my-proj # Explicit account/project (branch selects environment)
zuplo deploy --environment staging # Explicitly target a named environment
The default branch that maps to the production environment can be changed in the Zuplo portal.
Polling timeout: Default polls every 1s for 150s. Override with environment variables:
POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy
Even if the CLI times out, the deployment continues. Check status in the Zuplo portal.
zuplo deleteDelete a deployed environment by URL.
zuplo delete --url https://my-api-dev-123abc.zuplo.app
zuplo delete --url https://my-api-dev-123abc.zuplo.app --wait # Wait for completion
zuplo testRun API tests from the tests/ directory against a deployment endpoint.
zuplo test --endpoint https://your-api-123abc.zuplo.app # Run all tests
zuplo test --endpoint https://your-api.zuplo.app --filter 'auth' # Filter by name
zuplo test --endpoint https://your-api.zuplo.app --filter '/api\/v1/' # Filter by regex
MY_VAR=example zuplo test --endpoint https://your-api.zuplo.app # With env vars
zuplo variable createzuplo variable create \
--name API_KEY \
--value my-secret-key \
--is-secret true \
--branch main
zuplo variable create \
--name BASE_URL \
--value https://api.example.com \
--is-secret false \
--branch production \
--account my-acct \
--project my-proj
zuplo variable updatezuplo variable update --name API_KEY --value new-secret-key --branch main
Tunnels provide secure connectivity from Zuplo's edge to private/on-premises backends without exposing them to the internet. The tunnel agent runs inside your network and makes an outbound connection to Zuplo.
zuplo tunnel createzuplo tunnel create --tunnel-name my-tunnel
zuplo tunnel create --tunnel-name prod-tunnel --account my-acct
zuplo tunnel listzuplo tunnel list
zuplo tunnel list --account my-acct
zuplo tunnel describezuplo tunnel describe --tunnel-id tnl_xxxxx
zuplo tunnel deletezuplo tunnel delete # Interactive selection
zuplo tunnel delete --account my-acct
zuplo tunnel rotate-tokenRotate the authentication token for a tunnel.
zuplo tunnel rotate-token --tunnel-id tnl_xxxxx
zuplo tunnel services describeView the services configuration for a tunnel.
zuplo tunnel services describe --tunnel-id tnl_xxxxx
zuplo tunnel services updateUpdate services config from a JSON file.
zuplo tunnel services update --tunnel-id tnl_xxxxx --configuration-file ./services.json
zuplo openapi mergeMerge an external OpenAPI file into the Zuplo project (into routes.oas.json by default).
zuplo openapi merge --source openapi.yaml # From local file
zuplo openapi merge -s https://api.example.com/openapi.json # From URL
zuplo openapi merge --source openapi.yaml --destination ./config/api.oas.json # Custom dest
zuplo openapi merge --source openapi.yaml --merge-mode operation-id # Match by operationId
zuplo openapi merge --source openapi.yaml --prepend-path /v1 # Prepend path prefix
zuplo openapi merge --source openapi.yaml --watch # Watch for changes
Merge modes: path-method (default) or operation-id.
zuplo openapi convertConvert OpenAPI files between JSON and YAML.
zuplo openapi convert --input openapi.yaml --json # YAML to JSON
zuplo openapi convert -i openapi.json --yaml -o api-spec.yaml # JSON to YAML with custom output
zuplo openapi convert --input openapi.yaml --json --watch # Watch mode
zuplo openapi overlayApply an OpenAPI Overlay to an OpenAPI document.
zuplo openapi overlay --input openapi.json --overlay changes.json --output result.json
zuplo openapi overlay -i api.yaml -l overlay.yaml -o result.yaml --yaml
zuplo openapi overlay --input openapi.json --overlay changes.json --output result.json --watch
zuplo mtls-certificate createzuplo mtls-certificate create \
--name my_cert \
--cert ./cert.pem \
--key ./key.pem \
--environment-type production
# Multiple environment types:
zuplo mtls-certificate create \
--name dev_cert \
--cert ./cert.pem \
--key ./key.pem \
--environment-type development \
--environment-type preview
zuplo mtls-certificate listzuplo mtls-certificate list
zuplo mtls-certificate list --account my-acct --project my-proj
Additional mTLS commands: mtls-certificate describe, mtls-certificate update, mtls-certificate delete, mtls-certificate disable.
zuplo source upgradeUpdate project structure to latest conventions.
zuplo source upgrade
npx create-zuplo-api@latest # Interactive
npx create-zuplo-api@latest my-api # Named project
npx create-zuplo-api@latest my-api --example my-ex # From example template
npx create-zuplo-api@latest my-api --eslint --prettier # With tooling
All commands support:
--help - Print help message--api-key <key> - API key for authentication (or use ZUPLO_API_KEY env var)Enable verbose output for troubleshooting:
zuplo deploy --log-level debug # Debug-level output
zuplo dev --log-level verbose # Most verbose output
The CLI requires access to:
dev.zuplo.com - Zuplo public APIstorage.zuploedge.com - Project asset uploads during deployLocal development additionally needs:
*.zuploedge.com - Various services (API keys, rate limiting, etc.)export ZUPLO_DO_NOT_TRACK=1
npx create-zuplo-api@latest my-api
cd my-api
npx zuplo login
npx zuplo init
npx zuplo dev
Set ZUPLO_API_KEY and run zuplo deploy. Do NOT pass --environment in normal CI/CD — the CLI reads the current git branch and maps it to the matching Zuplo environment automatically (the default branch, typically main, maps to the production environment). Since CI checks out the branch being built, the correct environment is selected for you.
export ZUPLO_API_KEY=zpka_xxxxx
npx zuplo deploy --account my-account --project my-project
The default branch (the one that deploys to the production environment) can be changed in the Zuplo portal.
Only pass --environment when the branch-based mapping doesn't apply, for example:
staging first, then promote to production:export ZUPLO_API_KEY=zpka_xxxxx
npx zuplo deploy --account my-account --project my-project --environment staging
npx zuplo link # Select account, project, environment
npx zuplo dev # Now has access to API keys, rate limiting, etc.
npx zuplo openapi merge --source ./my-api-spec.yaml
npx zuplo dev