OverviewOverview

CLI Overview

@notation/cli provides the notation binary for building, deploying, and inspecting Notation applications. Every command isolates state per stage and selects terminal or JSON output automatically.

Installation

@notation/cli requires Node.js >=22.13.

Install it as a development dependency so local runs and CI share the same version:

Terminal
 add -d @notation/cli

Add scripts to package.json to invoke commands without installing the binary globally:

package.json
{
  "scripts": {
    "notation": "notation",
    "plan": "notation plan",
    "deploy": "notation deploy"
  }
}

Run any command through your package manager once the script is configured:

Terminal
 run notation plan --stage prod

You can also invoke ./node_modules/.bin/notation directly or run one-off commands without editing package.json:

Terminal
 @notation/cli plan --stage prod

Commands

The notation binary exposes seven subcommands:

CommandPurpose
notation deployCompiles your app, checks drift, and converges cloud resources for a stage
notation planPreviews creates, updates, replacements, and deletions without modifying infrastructure
notation destroyDeletes all tracked resources for a stage in reverse dependency order
notation watchWatches project files and automatically rebuilds and redeploys changes
notation compileBundles infrastructure and runtime modules into dist/ without resolving a stage
notation dashboardStarts a local web UI on port 6682 to inspect live stage state
notation vizEvaluates the infrastructure graph for a stage and prints a Mermaid Live Editor URL

Shared flags

Most commands accept shared flags for project targeting and output formatting (see CLI Flags for the full matrix):

FlagPurpose
--config <path>Loads a specific notation.config.ts and resolves paths from its directory
--stage <stage>Overrides defaultStage for any command other than compile
--jsonForces JSON output on deploy, plan, and destroy
--prettyForces readable terminal lines on deploy, plan, and destroy

--config

By default, Notation searches upward from the working directory for notation.config.ts. Passing --config <path> loads a specific config file and resolves project paths from its directory.

Pass --config to target an application outside your current working directory:

Terminal
 run notation plan --config apps/orders/notation.config.ts --stage prod

plan, deploy, and destroy preserve --config in printed follow-up and resume commands.

--stage

Every command except compile targets an <app>:<stage> deployment. Pass --stage <stage> to override defaultStage in notation.config.ts.

Target a stage on the command line without editing notation.config.ts:

Terminal
 run notation deploy --stage prod

If neither --stage nor defaultStage is set, the command exits with an error. When resuming deploy or destroy with --execution-id, omit --stage so Notation reads the saved stage from state.

Output formatting

deploy, plan, and destroy format output for humans in interactive terminals and CI, and switch to JSON automatically when piped outside CI. Pass --json to force JSON output (Plan JSON for plan, NDJSON events for deploy and destroy) or --pretty to force readable lines when piping.

Pipe notation plan --json directly into tools like jq because logs and diagnostics redirect to stderr:

Terminal
./node_modules/.bin/notation plan --json --stage prod | jq '.nodes[] | { id, decision }'

During deploy --json or destroy --json, each line on stdout carries "version": 1 alongside the reconciler payload:

stdout (NDJSON)
{"version":1,"level":"info","event":"reconciler.deploy.decision","resourceId":"orderQueue","resourceType":"aws/sqs/Queue","decision":"create"}

Error handling

Stack frames originating inside compiled dist/ bundles map back to your original .ts files and line numbers. Before printing any thrown error to stderr, the CLI scrubs recorded secret values with <hidden> and prints setup guidance when AWS credentials are missing.

When AWS credentials cannot be resolved during deploy, the CLI writes setup instructions to stderr:

stderr
AWS credentials not found.

Ensure you have a default profile set up in ~/.aws/credentials.

If using another profile run AWS_PROFILE=otherProfile notation deploy.

Exit codes

Commands exit with 0 on success and 1 on runtime errors, validation failures, or invalid CLI flags. notation watch also exits with 1 after finishing any active deploy if notation.config.ts changes.