CLI reference

The Nango CLI lets you initialize projects, develop integration functions locally, run dry runs against live connections, and deploy to your Nango environment.

Installation

Global install
npx (no install)

npm install -g nango

npx nango <command>

After installing, verify the version:

nango version

Authentication

The CLI authenticates using secret keys stored in environment variables. Add these to a .env file inside your nango-integrations folder:

NANGO_SECRET_KEY_DEV=xxxx-xxx-xxxx
NANGO_SECRET_KEY_PROD=xxxx-xxx-xxxx

Get your keys from Settings > Environment Settings in the Nango dashboard. Toggle between dev and prod environments in the left nav bar.

For self-hosted instances, set NANGO_HOSTPORT to your instance URL (e.g. http://localhost:3003).

Project structure

After running nango init, your integration folder looks like this:

nango-integrations/
├── .env                        # Secret keys and env config
├── index.ts                    # Imports all function files
├── package.json
├── tsconfig.json
└── github/                     # One folder per integration ID
    ├── syncs/
    │   └── fetchIssues.ts
    ├── actions/
    │   └── createIssue.ts
    └── on-events/
        └── pre-connection-deletion.ts

Commands

nango init

Initializes a new Nango integrations project in the specified directory.

nango init [path]

Arguments

Argument	Description
`path`	Directory to initialize in. Defaults to the current directory.

Options

Option	Description
`--ai [claude\|cursor...]`	Generate AI agent instruction files for Claude Code or Cursor.
`--copy`	Copy files only — skip `npm install` and pre-compilation.

Example

# Initialize in a new folder
nango init nango-integrations

# Initialize with Cursor AI instructions
nango init nango-integrations --ai cursor

nango create

Creates a new integration function scaffold (sync, action, or on-event script).

nango create [integration] [name]

Arguments

Argument	Description
`integration`	Integration ID (e.g. `my-github-integration`). Prompted if omitted.
`name`	Function name (e.g. `list-repos`). Prompted if omitted.

Options

Option	Description
`--sync`	Create a sync scaffold.
`--action`	Create an action scaffold.
`--on-event`	Create an on-event script scaffold.

Example

# Interactive (prompts for function type, integration, and name)
nango create

# Pass integration and name as positional arguments with type flag
nango create my-github-integration list-repos --sync

nango dev

Starts a local TypeScript watcher that compiles your integration functions as you edit them.

nango dev

Run this while writing functions to get instant type checking and compilation feedback. Example

# In your nango-integrations directory
nango dev

nango compile

Compiles all integration functions once without watching for changes. Useful for CI or one-off builds.

nango compile

nango deploy

Deploys compiled integration functions to a Nango environment.

nango deploy [environment]

Arguments

Argument	Description
`environment`	Target environment: `dev` or `prod`. Prompted if omitted.

Options

Option	Description
`-v, --version <version>`	Tag this deployment with a version string.
`-s, --sync <syncName>`	Deploy only a specific sync.
`-a, --action <actionName>`	Deploy only a specific action.
`-i, --integration <integrationId>`	Deploy all scripts for a specific integration.
`--allow-destructive`	Allow destructive changes (e.g. removing a sync or renaming a model) without confirmation.

Example

# Deploy all functions to dev
nango deploy dev

# Deploy to prod with version tag
nango deploy prod --version 1.2.0

# Deploy only one integration
nango deploy dev --integration my-github-integration

# Non-interactive CI deploy
nango deploy prod --auto-confirm

Destructive changes (removing syncs or renaming models) always require explicit confirmation, even with --auto-confirm. Pass --allow-destructive to bypass this.

nango dryrun

Tests a sync or action locally against a real connection without writing data to Nango. Useful for debugging during development.

nango dryrun [name] [connection_id]

Arguments

Argument	Description
`name`	Name of the sync or action. Prompted if omitted.
`connection_id`	Connection ID to run against. Prompted if omitted.

Options

Option	Description
`-e, --environment <env>`	Nango environment to use (`dev` or `prod`). Prompted if omitted.
`-i, --input <json>`	Input for actions as a JSON string or `@path/to/file.json`.
`-l, --lastSyncDate <date>`	Override the last sync date for incremental syncs (any string parseable by `new Date()`).
`-m, --metadata <json>`	Stub metadata for the run as a JSON string or `@path/to/file.json`.
`-c, --checkpoint <json>`	Stub sync checkpoint as a JSON string or `@path/to/file.json`.
`--variant <variant>`	Sync variant to run. Defaults to the base variant.
`--integration-id <id>`	Integration ID. Inferred from the connection if not provided.
`--validate`	Enforce input, output, and record validation.
`--save`	Save all dry-run responses to `<integration>/tests/<name>.test.json` for unit tests.
`--diagnostics`	Display performance diagnostics (memory, CPU).

Example

# Interactive
nango dryrun

# Run a specific sync
nango dryrun github-issues user-123 -e dev

# Run an action with input
nango dryrun create-issue user-123 -e dev --input '{"title": "Test"}'

# Pass input from a file
nango dryrun create-issue user-123 -e dev --input @fixtures/issue.json

# Test with a specific last sync date
nango dryrun github-issues user-123 -e dev --lastSyncDate "2024-01-01"

nango generate:docs

Generates documentation for your integration functions from their TypeScript definitions.

nango generate:docs

Options

Option	Description
`-p, --path <path>`	Path to generate docs for. Defaults to the current directory.
`--integration-templates`	Use this flag when generating for the nango integration-templates repo.

nango generate:tests

Generates test scaffolds for your integration scripts.

nango generate:tests

Options

Option	Description
`-i, --integration <id>`	Generate tests for a specific integration only.
`-s, --sync <name>`	Generate tests for a specific sync.
`-a, --action <name>`	Generate tests for a specific action.

nango clone

Clones integration templates from the nango integration-templates repository.

nango clone <template>

Arguments

Argument	Description
`template`	Template path to clone (e.g. `github`, `github/actions`, `github/actions/list-repos`).

Options

Option	Description
`-f, --force`	Overwrite existing files without prompting.

Example

# Clone all GitHub templates
nango clone github

# Clone only GitHub actions
nango clone github/actions

# Clone a specific action
nango clone github/actions/list-repos

nango migrate-to-zero-yaml

Migrates an existing nango.yaml-based project to the zero-YAML TypeScript format. Run this once if you have a legacy project.

nango migrate-to-zero-yaml

nango version

Prints the installed CLI version.

nango version

Global flags

These flags are available on all commands:

Flag	Description
`--auto-confirm`	Automatically confirm all prompts. Useful in CI pipelines.
`--debug`	Enable verbose debug logging.
`--no-interactive`	Disable interactive prompts. Required values must be passed as flags.
`--no-dependency-update`	Skip automatic `package.json` updates and dependency installs.

Interactive mode

By default, the CLI prompts you for any missing arguments. For example, running nango create without flags shows a menu to select the function type, integration, and name. Disable interactive mode in CI or scripts:

# Via flag
nango deploy prod --no-interactive

# Automatically disabled when CI=true is set
CI=true nango deploy prod

Environment variables

Place these in a .env file inside your nango-integrations folder.

Variable	Default	Description
`NANGO_SECRET_KEY_DEV`	—	Secret key for the `dev` environment.
`NANGO_SECRET_KEY_PROD`	—	Secret key for the `prod` environment.
`NANGO_HOSTPORT`	`https://api.nango.dev`	Nango instance URL. Change for self-hosted deployments.
`NANGO_CLI_UPGRADE_MODE`	`prompt`	How to handle CLI upgrades: `prompt`, `auto`, or `ignore`.
`NANGO_DEPLOY_AUTO_CONFIRM`	`false`	Skip deployment confirmation prompts. Destructive changes still require `--allow-destructive`.
`NANGO_CLI_DEPENDENCY_UPDATE`	`true`	Set to `false` to disable automatic dependency installs (same as `--no-dependency-update`).

Dependency management

The CLI automatically detects your package manager and installs dependencies when needed. Detection order:

packageManager field in package.json (Corepack standard)
Lock files: pnpm-lock.yaml, yarn.lock, bun.lockb / bun.lock
Falls back to npm

Supported package managers: npm, pnpm, yarn, bun. Use --no-dependency-update to opt out of automatic installs — for example, in monorepos where dependency management is handled at the workspace root.

When --no-dependency-update is set, ensure all dependencies are already installed before running commands.

Getting help

Run any command with --help to see its options:

nango --help
nango deploy --help
nango dryrun --help

Documentation Index

​Installation

​Authentication

​Project structure

​Commands

​nango init

​nango create

​nango dev

​nango compile

​nango deploy

​nango dryrun

​nango generate:docs

​nango generate:tests

​nango clone

​nango migrate-to-zero-yaml

​nango version

​Global flags

​Interactive mode

​Environment variables

​Dependency management

​Getting help

Installation

Authentication

Project structure

Commands

nango init

nango create

nango dev

nango compile

nango deploy

nango dryrun

nango generate:docs

nango generate:tests

nango clone

nango migrate-to-zero-yaml

nango version

Global flags

Interactive mode

Environment variables

Dependency management

Getting help