# CLI

> Install the Nodaro CLI with npm or as a standalone binary, sign in once per instance, and run workflows, apps and single nodes from a terminal or a CI job.

Source: https://nodaro.ai/docs/developers/cli

The **Nodaro CLI** (`@nodaro/cli`) is a command-line client for Nodaro. It lists and runs workflows, runs published apps, runs a single node without a workflow, and follows each run until it finishes. It keeps several signed-in profiles side by side and prints JSON for scripts, so it fits terminal work, cron jobs and CI pipelines.

The CLI is a thin wrapper around the [TypeScript SDK](https://nodaro.ai/docs/developers/sdk). For an integration written in code, use the SDK directly.

## Install

**npm**

The npm package runs on macOS, Linux and Windows. It needs Node.js 20 or later.

```bash
npm install -g @nodaro/cli
nodaro --version
```

To run one command without installing the package, use `npx`:

```bash
npx @nodaro/cli projects list
```

**macOS and Linux binary**

The standalone binary is a single file of about 60 MB. It needs no Node.js and starts in about 10 ms.

CLI releases are tagged `cli-vX.Y.Z` in the public repository. The repository's "latest" release belongs to the app, not to the CLI, so a `releases/latest/download/...` link never reaches a CLI binary. Find the newest `cli-v` tag first, then download from it:

```bash
# 1. The newest CLI version
NODARO_CLI_VERSION=$(curl -fsSL "https://api.github.com/repos/nodaroai/app.nodaro.ai/git/matching-refs/tags/cli-v?per_page=100" \
| grep -o '"refs/tags/cli-v[0-9][0-9.]*"' | tr -d '"' | sed 's#refs/tags/cli-v##' \
| sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1)
echo "Installing @nodaro/cli $NODARO_CLI_VERSION"

# 2. Your platform: darwin-arm64 (Apple silicon), darwin-x64 (Intel Mac), linux-x64 or linux-arm64
NODARO_CLI_PLATFORM=darwin-arm64

# 3. Download. -f fails on an HTTP error instead of saving the error page as the binary.
curl -fL "https://github.com/nodaroai/app.nodaro.ai/releases/download/cli-v$NODARO_CLI_VERSION/nodaro-$NODARO_CLI_PLATFORM" \
  -o /usr/local/bin/nodaro && chmod +x /usr/local/bin/nodaro
nodaro --version
```

**Windows binary**

In PowerShell, find the newest `cli-v` tag, then download `nodaro-windows-x64.exe`:

```powershell
$v = (Invoke-RestMethod "https://api.github.com/repos/nodaroai/app.nodaro.ai/git/matching-refs/tags/cli-v?per_page=100") |
ForEach-Object { $_.ref -replace '^refs/tags/cli-v', '' } |
Where-Object { $_ -match '^\d+\.\d+\.\d+$' } |
Sort-Object { [version]$_ } | Select-Object -Last 1
Invoke-WebRequest "https://github.com/nodaroai/app.nodaro.ai/releases/download/cli-v$v/nodaro-windows-x64.exe" -OutFile nodaro.exe
.\nodaro.exe --version
```

To pin a version, skip the first step and set the version yourself. Every CLI release and its binaries are listed under the [cli-v releases](https://github.com/nodaroai/app.nodaro.ai/releases?q=cli-v) of the public repository.

## Sign in

The CLI authenticates with a personal API token and saves it in a profile.

### Start the browser sign-in

Run `nodaro auth login`. The CLI opens your browser at the **Authorize Nodaro CLI** page of the Nodaro instance.

### Authorize the CLI

Sign in if needed, then click **Authorize**. Nodaro creates a personal API token named after your device and returns it to the terminal.

### Check the profile

Run `nodaro auth status`. It shows the profile name, the instance address and the token, masked.

If the browser flow fails, the CLI asks you to paste a token instead. To create a token yourself, open **Settings › API** in Nodaro and click **Create Token**. The full token is shown once. Personal API tokens are available on Nodaro Cloud and on Business edition installs. Read [Authentication](https://nodaro.ai/docs/developers/api/authentication) for how tokens work.

```bash
nodaro auth login                                   # browser sign-in
nodaro auth login --no-browser                      # paste a token instead
nodaro auth login --token "$NODARO_TOKEN"           # non-interactive, for CI
nodaro auth status [--profile <name>] [--json]      # show a profile, token masked
nodaro auth logout [--profile <name>]               # delete a saved profile
```

| Option of `auth login` | What it does |
| --- | --- |
| `--profile <name>` | The profile to save. The default is `production`. |
| `--token <token>` | Save this token without opening the browser or asking. |
| `--base-url <url>` | The Nodaro instance. The default is `https://app.nodaro.ai`. |
| `--no-browser` | Skip the browser and paste a token instead. |

The CLI stores profiles in `~/.config/nodaro/config.json`, readable only by your user (file mode `0600`). Set `NODARO_CONFIG_DIR` to keep the file in another folder.

## Use profiles for several instances

A **profile** is a saved instance address and token. Create one profile per instance, such as Nodaro Cloud, a staging install and a local install. Then choose one with `--profile`, which every command accepts:

```bash
nodaro auth login --profile prod    --base-url https://app.nodaro.ai
nodaro auth login --profile staging --base-url https://staging.example.com
nodaro auth login --profile local   --base-url http://localhost:3000

nodaro projects list --profile staging
```

A command without `--profile` uses the default profile. The default is `production` until you save a profile: the first profile you save becomes the default. So a single `nodaro auth login`, without flags, is all most people need.

## Choose a workspace

On an instance with organizations, work lives in **workspaces**. Choose one for a single command with `--workspace <id>`, for a shell or a CI job with `NODARO_WORKSPACE`, or save one on the profile with `nodaro workspace use <id>`. With none set, work happens in your personal space. See [Workspaces and organizations](https://nodaro.ai/docs/developers/cli/workspaces).

## Three ways to run something

The CLI covers the three ways Nodaro runs work. Choose the one that matches what you have built.

| Goal | Command |
| --- | --- |
| Run a saved workflow | `nodaro workflows run <workflowId>` |
| Run a published app, with its curated inputs and outputs | `nodaro apps run <slug> --input key=value` |
| Run a single node directly, without a workflow | `nodaro nodes run <type> --param key=value` |

`nodaro nodes run` is the CLI equivalent of the verb tools of the [MCP server](https://nodaro.ai/docs/mcp/tools), such as `generate_image` and `generate_video`. Every generation node answers at `POST /v1/<type>`, so any node that `nodaro nodes list` shows can run with `nodaro nodes run`. See [Run a single node](https://nodaro.ai/docs/developers/api/nodes) for the REST side.

Add `--watch` to wait until the run finishes:

```bash
nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge, cinematic" \
  --param provider=flux \
  --watch
```

Read [Parameters and input files](https://nodaro.ai/docs/developers/cli/params) for the `--param` syntax, and [Output and exit codes](https://nodaro.ai/docs/developers/cli/output) before you script the CLI.

## What the CLI does not cover

The CLI leaves out credits, developer apps, OAuth, pipelines, Reduce and the upload helpers. Use the [SDK](https://nodaro.ai/docs/developers/sdk) or the [REST API](https://nodaro.ai/docs/developers/api) for those.

Moving from the CLI to code is short. This is the SDK equivalent of `nodaro workflows run wf_abc`:

```ts

const nodaro = createClient({
baseUrl: "https://app.nodaro.ai",
auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})

const run = await nodaro.workflows.run("wf_abc")
```

## Next steps

  - [Commands](https://nodaro.ai/docs/developers/cli/commands): 
Every core command: projects, workflows, apps, nodes, models, pickers, executions and jobs.
  
  - [Parameters and input files](https://nodaro.ai/docs/developers/cli/params): 
How --param, --input and --params-file turn text into a request body.
  
  - [Output and exit codes](https://nodaro.ai/docs/developers/cli/output): 
JSON output, --watch and the exit codes to branch on in scripts.
  
  - [Examples](https://nodaro.ai/docs/developers/cli/examples): 
Cron jobs, CI gates, captions from a transcript and prompt wizard recipes.

## Frequently asked questions

### How do I install the Nodaro CLI?

Run npm install -g @nodaro/cli with Node.js 20 or later. Without Node.js, download the standalone binary for macOS, Linux or Windows from a cli-v release of the public GitHub repository. Check the install with nodaro --version.

### How do I sign in to the Nodaro CLI?

Run nodaro auth login. Your browser opens the Authorize Nodaro CLI page, you click Authorize, and the CLI receives a personal API token. In a CI job, pass a token directly with nodaro auth login --token.

### Where does the Nodaro CLI store my token?

In ~/.config/nodaro/config.json, with file permissions that let only your user read it. Set the NODARO_CONFIG_DIR environment variable to keep the file in another folder.

### Can I use the CLI with a self-hosted Nodaro install?

Yes. Save a profile with --base-url set to the address of your install, for example nodaro auth login --profile local --base-url http://localhost:3000, then add --profile local to your commands.

### Should I use the CLI or the SDK?

Use the CLI for terminal work, cron jobs, CI pipelines and quick checks. For an integration written in code, use the TypeScript SDK. The CLI is a thin wrapper around the SDK, so everything the CLI does, the SDK does too.