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)
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
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.
Arguments
| Argument | Description |
|---|
path | Directory to initialize in. Defaults to the current directory. |
| 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. |
# 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]
| Argument | Description |
|---|
integration | Integration ID (e.g. my-github-integration). Prompted if omitted. |
name | Function name (e.g. list-repos). Prompted if omitted. |
| Option | Description |
|---|
--sync | Create a sync scaffold. |
--action | Create an action scaffold. |
--on-event | Create an on-event script scaffold. |
# 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.
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 deploy
Deploys compiled integration functions to a Nango environment.
nango deploy [environment]
| Argument | Description |
|---|
environment | Target environment: dev or prod. Prompted if omitted. |
| 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. |
# 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]
| Argument | Description |
|---|
name | Name of the sync or action. Prompted if omitted. |
connection_id | Connection ID to run against. Prompted if omitted. |
| 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). |
# 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.
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.
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.
Arguments
| Argument | Description |
|---|
template | Template path to clone (e.g. github, github/actions, github/actions/list-repos). |
| Option | Description |
|---|
-f, --force | Overwrite existing files without prompting. |
# 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.
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
