--- title: Command reference description: 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](/docs/cli#authenticate). 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 `/notiflows//` folder, so you can omit the handle argument. ## Auth ### `login` 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. ```bash notiflows login notiflows login --token nf_at_xxx ``` ### `logout` Remove the stored credentials. ```bash notiflows logout ``` ### `whoami` Confirm the authenticated account and the active project. ```bash 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. ```bash notiflows init my-app ``` ### `project list` List the projects your account token can access (read-only). ```bash notiflows project list ``` ### `project get ` Show details for one project (read-only). ```bash 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. ```bash 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). ```bash 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. ```bash 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`. ```bash 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. ```bash notiflows notiflow get welcome-series ``` ### `notiflow list` List the notiflows in the project (summaries, no steps). ```bash 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). ```bash notiflows notiflow pull welcome-series ``` ### `notiflow push [handle]` Push a single notiflow (upsert draft). Add `--publish` to publish afterward; `--force` to overwrite on conflict. ```bash notiflows notiflow push welcome-series --publish ``` ### `notiflow publish [handle]` Publish the current draft version so it becomes live for execution. ```bash notiflows notiflow publish welcome-series ``` ### `notiflow rollback ` Discard unpublished draft changes and revert to the published version. ```bash notiflows notiflow rollback welcome-series ``` ### `notiflow activate ` / `notiflow deactivate ` Toggle whether a notiflow can be triggered (the active flag). ```bash notiflows notiflow activate welcome-series notiflows notiflow deactivate welcome-series ``` ### `notiflow archive ` Archive (delete) a notiflow. ```bash notiflows notiflow archive welcome-series ``` ### `notiflow versions ` List a notiflow's version history. ```bash notiflows notiflow versions welcome-series ``` ### `notiflow validate [handle]` Validate the notiflow's current draft on the server. Returns whether the current version is valid. ```bash notiflows notiflow validate welcome-series ``` ### `notiflow open [handle]` Open the notiflow in the dashboard in your browser. ```bash 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` `` — a recipient's external id (repeatable). - `--topic` `` — run to all subscribers of a topic instead of explicit recipients. - `--data` / `-d` `` — a JSON object of template/condition variables. - `--actor` `` — 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`. ```bash # 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. ```bash notiflows channel list ``` ### `channel get ` Show one channel by handle. ```bash notiflows channel get transactional-email ``` ## Related - [Notiflows as code](/docs/cli/notiflows-as-code) — the file format these commands read and write. - [CI/CD](/docs/cli/ci-cd) — running these commands in a pipeline. - [MCP server](/docs/ai/mcp) — the same operations as MCP tools inside an AI editor.