Introduction

notploy is the official command-line client for Notploy. It talks to the same API the dashboard uses, so anything you can do in the interface — create projects, deploy applications, provision databases, inspect logs, clean up servers — you can do from a shell, a CI job or a Makefile.

The command surface is generated from the API specification rather than written by hand: 57 command groups and 604 commands, each one mapping to exactly one API operation.

Requirements

• Node.js 18 or newer — the CLI declares >=18.0.0 in its engines field.
• A Notploy instance you can reach over HTTP — self-hosted or Notploy Cloud.
• An API key with the permissions you need. See Authentication.

Installation

npm install -g @notploy/cli

The package installs a single binary called notploy:

notploy --version

pnpm add -g @notploy/cli and bun add -g @notploy/cli work the same way.

Authenticate

notploy auth -u https://panel.example.com -t "$NOTPLOY_API_KEY"

The CLI validates the key against your instance and stores it for later commands. Environment variables (NOTPLOY_URL + NOTPLOY_API_KEY) are an alternative that is a better fit for CI — both are covered in Authentication.

How commands work

Every command follows the same shape:

notploy <group> <command> [options]

Flags and behaviour:

• Flags mirror the API inputs, written in camelCase: --environmentId is sent as environmentId. The command reference lists them per command.
• Required flags (marked Yes in the reference) abort the command when missing — commander refuses to run it. Everything else is optional, and anything you leave out is omitted from the request entirely, so the server applies its own default.
• Booleans are passed without a value: --enableDockerCleanup. They are only sent when you include them.
• Numbers are converted before they are sent, so --port 5432 reaches the API as a number, not a string.
• Every command accepts --json to print the raw API response instead of the formatted output.

Help

notploy --help                    # groups
notploy application --help        # commands in a group
notploy application create --help # options of one command

Running notploy or notploy <group> without a command prints the same help, and notploy --help is safe to paste into any script.

Output and exit codes

Because failures are non-zero exits, the CLI drops straight into pipelines: notploy application deploy --applicationId "$APP_ID" && echo deployed.

How requests are made

The CLI calls the public API directly, so you can reproduce any command by hand:

• Endpoint — {url}/api/trpc/{group}.{command}, for example POST /api/trpc/application.create.
• Authentication — an x-api-key header with your key.
• Reads (GET) pass the inputs as a single URL-encoded input query parameter; writes (POST) send { "json": { ... } } as the body.

This is the same contract described in the API reference, which is useful when the CLI does not expose something you need.

Quick start

Create a project, add an environment, wire up a Git application and deploy it:

# 1. Point the CLI at your instance
notploy auth -u https://panel.example.com -t "$NOTPLOY_API_KEY"

# 2. Look around
notploy project all
notploy server all

# 3. Create a project, then an environment inside it
notploy project create --name my-project --description "My first project" --env production
notploy environment create --name production --description "Production" --projectId <projectId>

# 4. Create an application in that environment
notploy application create --name my-app --environmentId <environmentId>

# 5. Connect the Git repository it should build from
notploy application save-github-provider \
  --applicationId <applicationId> \
  --githubId <githubId> \
  --owner <owner> \
  --repository <repository> \
  --branch main \
  --buildPath / \
  --triggerType push

# 6. Deploy, then follow the deployment
notploy application deploy --applicationId <applicationId>
notploy deployment all --applicationId <applicationId>
notploy deployment read-logs --deploymentId <deploymentId>

Where to go next

• Authentication — API keys, the config file, environment variables and precedence.
• Command reference — all 57 groups, including every flag and its allowed values.
• API reference — the same operations over HTTP.