Agent Skill · Zuplo

zuplo-cli

Zuplo CLI helper for developing and managing Zuplo API Gateway projects. Use when the user wants to run zuplo CLI commands, deploy, manage environment variables, set up tunnels, run tests, initialize projects, work with OpenAPI specs, or do local development with the Zuplo platform.

View SKILL.md on GitHub → Source repository Provider profile

Provider: Zuplo Path in repo: skills/zuplo-cli/SKILL.md

Skill body

Zuplo CLI

This skill helps developers use the Zuplo CLI to develop and manage their Zuplo API Gateway projects.

How to look up Zuplo documentation

Use these sources in priority order:

Local docs (preferred): Read from node_modules/zuplo/docs/cli/ — version-matched, always available offline. Check both the project root and parent directories for monorepos.
MCP server tools: Use search-zuplo-docs and ask-question-about-zuplo if the Zuplo MCP server is connected.
Fetch docs via URL: Fetch https://zuplo.com/docs/cli/overview or discover all pages at https://zuplo.com/docs/llms.txt.

When to Use This Skill

Use this skill when the user:

Wants to deploy their Zuplo project
Needs to start local development
Wants to run API tests
Needs to manage environment variables
Wants to create, list, or manage tunnels
Needs to initialize or link a project
Wants to work with OpenAPI specs (merge, convert, overlay)
Asks about Zuplo CLI commands or options
Needs to manage mTLS certificates
Wants to create a new Zuplo project

Prerequisites

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 zuplo commands shown below should be run via npx zuplo, pnpx zuplo, or equivalent. The zuplo prefix is shown without npx for brevity.

Authentication

Two methods:

OAuth (interactive)

Uses device flow authentication — opens a browser for login and returns a refresh token for session persistence.

zuplo login

API Key (CI/CD and automation)

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.

Zuplo Project Structure

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)

Key files

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.

The `$import()` syntax

JSON config files use $import() to reference code modules:

$import(@zuplo/runtime) - Built-in Zuplo modules
$import(./modules/my-handler) - Custom modules in modules/ directory

CLI Commands Reference

Local Development

`zuplo dev`

Start 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:

API server: 9000 (default)
Route designer/editor: 9100 (default)
Docs server: 9200 (default)

To use Zuplo services (API keys, rate limiting) locally, first run zuplo link to connect to a remote environment.

`zuplo editor`

Start just the OpenAPI Designer (route editor) standalone.

zuplo editor                    # Default port 9100
zuplo editor --port 8080        # Custom port

`zuplo docs`

Start 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

Project Management

`zuplo link`

Link 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 list`

List all deployed Zuplo APIs/environments.

zuplo list
zuplo list --account my-acct --project my-proj

`zuplo project create`

Create a new project in your account.

zuplo project create --name my-api-project
zuplo project create --name my-proj --account my-acct

Deployment

`zuplo deploy`

Deploy the current directory. Uses the current git branch name as the environment name by default.

zuplo deploy                                        # Uses git branch as environment name
zuplo deploy --environment my-env                   # Override environment name
zuplo deploy --account my-acct --project my-proj    # Explicit account/project

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 delete`

Delete 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

Testing

`zuplo test`

Run 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

Environment Variables

`zuplo variable create`

zuplo 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 update`

zuplo variable update --name API_KEY --value new-secret-key --branch main

Tunnels

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 create`

zuplo tunnel create --tunnel-name my-tunnel
zuplo tunnel create --tunnel-name prod-tunnel --account my-acct

`zuplo tunnel list`

zuplo tunnel list
zuplo tunnel list --account my-acct

`zuplo tunnel describe`

zuplo tunnel describe --tunnel-id tnl_xxxxx

`zuplo tunnel delete`

zuplo tunnel delete                         # Interactive selection
zuplo tunnel delete --account my-acct

`zuplo tunnel rotate-token`

Rotate the authentication token for a tunnel.

zuplo tunnel rotate-token --tunnel-id tnl_xxxxx

`zuplo tunnel services describe`

View the services configuration for a tunnel.

zuplo tunnel services describe --tunnel-id tnl_xxxxx

`zuplo tunnel services update`

Update services config from a JSON file.

zuplo tunnel services update --tunnel-id tnl_xxxxx --configuration-file ./services.json

OpenAPI Tools

`zuplo openapi merge`

Merge 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 convert`

Convert 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 overlay`

Apply 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

mTLS Certificates

`zuplo mtls-certificate create`

zuplo 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 list`

zuplo 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.

Source Management

`zuplo source upgrade`

Update project structure to latest conventions.

zuplo source upgrade

Scaffolding a New Project (without CLI installed)

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

Global Options

All commands support:

--help - Print help message
--api-key <key> - API key for authentication (or use ZUPLO_API_KEY env var)

Debug Logging

Enable verbose output for troubleshooting:

zuplo deploy --log-level debug       # Debug-level output
zuplo dev --log-level verbose        # Most verbose output

Network Connectivity

The CLI requires access to:

dev.zuplo.com - Zuplo public API
storage.zuploedge.com - Project asset uploads during deploy

Local development additionally needs:

*.zuploedge.com - Various services (API keys, rate limiting, etc.)

Analytics Opt-Out

export ZUPLO_DO_NOT_TRACK=1

Common Workflows

New project setup

npx create-zuplo-api@latest my-api
cd my-api
npx zuplo login
npx zuplo init
npx zuplo dev

Deploy from CI/CD

export ZUPLO_API_KEY=zpka_xxxxx
npx zuplo deploy --environment production

Connect local dev to remote services

npx zuplo link    # Select account, project, environment
npx zuplo dev     # Now has access to API keys, rate limiting, etc.

Import an existing OpenAPI spec

npx zuplo openapi merge --source ./my-api-spec.yaml
npx zuplo dev

zuplo-cli

Skill body

Zuplo CLI

How to look up Zuplo documentation

When to Use This Skill

Prerequisites

Authentication

OAuth (interactive)

API Key (CI/CD and automation)

Zuplo Project Structure

Key files

The $import() syntax

CLI Commands Reference

Local Development

zuplo dev

zuplo editor

zuplo docs

Project Management

zuplo link

zuplo list

zuplo project create