Command reference

The complete Notiflows CLI command reference — authentication, project inspection, sync (pull/push/diff), notiflow lifecycle, triggering runs, and channels.

Every command is shown with the notiflows binary; the shorthand nf is equivalent (nf notiflow push). Authenticated commands resolve the account token and project using the resolution precedence. Most commands accept --json for machine-readable output.

Context-aware single-notiflow commands. notiflow get, push, pull, validate, publish, open, and run infer the target handle from your current directory when you're inside a <notiflowsDir>/notiflows/<handle>/ folder, so you can omit the handle argument.

Auth

Authenticate with an account token (prefix nf_at_). Prompts for the token, or pass --token. Stores it at ~/.config/notiflows/credentials.json (mode 0600). Optional --base-url overrides the API endpoint.

notiflows login
notiflows login --token nf_at_xxx

`logout`

Remove the stored credentials.

notiflows logout

`whoami`

Confirm the authenticated account and the active project.

notiflows whoami

Project

`init [project]`

Create notiflows.json and the .notiflows/notiflows/ working tree in the current directory. The optional project argument writes the project slug into the config.

notiflows init my-app

`project list`

List the projects your account token can access (read-only).

notiflows project list

`project get <slug>`

Show details for one project (read-only).

notiflows project get my-app

Sync

These commands operate on the whole local working tree.

`pull`

Pull every notiflow in the project into local files, overwriting after one confirmation.

notiflows pull

`push [--publish]`

Push all changed local notiflows back to the server (each push creates or updates a draft version). Flags:

--publish — publish each notiflow after pushing.
--force / -f — skip the confirmation prompt and the conflict check (overwrite remote state).

notiflows push
notiflows push --publish

Idempotent and conflict-safe. Re-pushing unchanged content creates no new version, so push is safe to run on every deploy. Each push also sends an expected_sha (the version you pulled); if the notiflow changed on the server since you pulled, the push is rejected as a conflict — pull and re-push, or use --force to overwrite.

`diff [handle]`

Show the differences between local notiflow files and the server. Omit the handle to diff all local notiflows; add --json for machine-readable output.

notiflows diff
notiflows diff welcome-series
notiflows diff --json

Notiflow lifecycle

Single-notiflow commands under the notiflow topic.

`notiflow new [handle]`

Scaffold a new notiflow with a minimal configuration. Flags: --name/-n (display name), --steps/-s (comma-separated step types, e.g. email,wait,sms), --push/-p (push after creation), --force/-f.

notiflows notiflow new welcome-series --name "Welcome Series" --steps email,wait,email

`notiflow get [handle]`

Fetch a notiflow with its current and published version steps.

notiflows notiflow get welcome-series

`notiflow list`

List the notiflows in the project (summaries, no steps).

notiflows notiflow list

`notiflow pull [handle]`

Pull a single notiflow into local files. Respects existing files unless --force; --all pulls everything and prunes local directories no longer present on the server (destructive).

notiflows notiflow pull welcome-series

`notiflow push [handle]`

Push a single notiflow (upsert draft). Add --publish to publish afterward; --force to overwrite on conflict.

notiflows notiflow push welcome-series --publish

`notiflow publish [handle]`

Publish the current draft version so it becomes live for execution.

notiflows notiflow publish welcome-series

`notiflow rollback <handle>`

Discard unpublished draft changes and revert to the published version.

notiflows notiflow rollback welcome-series

`notiflow activate <handle>` / `notiflow deactivate <handle>`

Toggle whether a notiflow can be triggered (the active flag).

notiflows notiflow activate welcome-series
notiflows notiflow deactivate welcome-series

`notiflow archive <handle>`

Archive (delete) a notiflow.

notiflows notiflow archive welcome-series

`notiflow versions <handle>`

List a notiflow's version history.

notiflows notiflow versions welcome-series

`notiflow validate [handle]`

Validate the notiflow's current draft on the server. Returns whether the current version is valid.

notiflows notiflow validate welcome-series

`notiflow open [handle]`

Open the notiflow in the dashboard in your browser.

notiflows notiflow open welcome-series

Trigger

`notiflow run [handle]`

Trigger (run) a notiflow to send notifications. The run is attributed to the calling account token (it shows up as "Triggered by" the token in the dashboard). By default the published version runs, so the notiflow must be active and published.

Flags:

--recipient / -r <external_id> — a recipient's external id (repeatable).
--topic <topic> — run to all subscribers of a topic instead of explicit recipients.
--data / -d <json> — a JSON object of template/condition variables.
--actor <external_id> — the external id of the actor who caused the event.
--draft — run the current unpublished draft instead of the published version. The notiflow must be active, but need not be published.

You must provide at least one --recipient or a --topic.

# Run the published version
notiflows notiflow run welcome-series \
  -r user_123 \
  --data '{"first_name":"Ada"}'

# Multiple recipients + an actor
notiflows notiflow run order-shipped \
  -r user_123 -r user_456 \
  --actor user_789 \
  --data '{"order_id":"ORD-1"}'

# Target a topic
notiflows notiflow run product-updates --topic release-notes

# Test-run the current unpublished draft
notiflows notiflow run welcome-series --draft -r user_123

Channels

Channels are configured in the dashboard; the CLI surface is read-only.

`channel list`

List the project's configured delivery channels.

notiflows channel list

`channel get <handle>`

Show one channel by handle.

notiflows channel get transactional-email

Notiflows as code — the file format these commands read and write.
CI/CD — running these commands in a pipeline.
MCP server — the same operations as MCP tools inside an AI editor.

On this page