> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nagare.smtdfc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> All commands and options of the nagare CLI.

```bash theme={null}
nagare [command] [option]
```

| Command | Description |
| - | - |
| [`nagare gateway start`](#nagare-gateway-start) | Start the gateway. |
| [`nagare gateway stop`](#nagare-gateway-stop) | Stop the gateway. |
| [`nagare web`](#nagare-web) | Serve and open the web UI. |
| [`nagare auth token`](#nagare-auth-token) | Generate a login token. |
| [`nagare doctor`](#nagare-doctor) | Check the installation health. |
| [`nagare plugin build`](#nagare-plugin-build) | Build and package a plugin. |

## Global options

| Option | Description |
| - | - |
| `-v`, `--version` | Print the version. |
| `-h`, `--help` | View command help. |

## nagare gateway start

Start `nagare-gateway` in the foreground of the current terminal. The PID is saved to `~/.nagare/.gateway.pid`.

```bash theme={null}
nagare gateway start [--host <host>]
```

| Option | Description |
| - | - |
| `--host <host>` | The address the gateway listens on. Default is `localhost`. |
| `-d`, `--debug` | Debug mode, for developing Nagare from source. |

The first run creates an RSA key pair in the system keyring (service `nagare.security.keyring`). The gateway uses the public key to verify tokens.

> [!WARNING]
>
> If you set `--host 0.0.0.0`, the gateway can be accessed from other machines on the network. All APIs still require a token, but think carefully because Nagare can control your machine.

## nagare gateway stop

Send a shutdown request to the running gateway.

```bash theme={null}
nagare gateway stop
```

Prints `Nagare gateway shutdown requested.` on success, or `Nagare gateway is not running.` if the gateway is not running.

## nagare web

Serve the built-in web UI and open the browser with automatic login.

```bash theme={null}
nagare web [--addr <addr>] [--gateway <url>] [--token <token>] [--no-open]
```

| Option | Default | Description |
| - | - | - |
| `--addr` | `127.0.0.1:3005` | The HTTP address of the web UI. You can change the port with the `NAGARE_WEB_UI_PORT` variable. |
| `--gateway` | `http://localhost:9832` | The gateway URL used for automatic login. Taken from `NAGARE_GATEWAY_URL` or `NAGARE_GATEWAY_PORT` if set. |
| `--token` | Auto-generated | The token used for automatic login. |
| `--no-open` | `false` | Do not open the browser; only print the login URL. |

## nagare auth token

Generate a JWT token for logging into the web UI, desktop app, or calling the API.

```bash theme={null}
nagare auth token
# Your token is: eyJhbGciOi...
```

The token is signed with the RSA key in the keyring and is valid for 60 hours.

## nagare doctor

Check the components of Nagare:

| Check | Details |
| - | - |
| Gateway process | PID file exists and the process is alive. |
| Gateway HTTP reachable | Can access `http://localhost:<port>/ws`. |
| Plugin IPC socket | Plugin socket/pipe exists and is connectable. |
| SQLite database | `~/.nagare/databases/nagare.db` is valid. |
| RSA keyring | Can read the RSA key pair in the keyring. |
| Module: nagare\_vector | Module exists in `~/.nagare/modules`. |

```bash theme={null}
nagare doctor
```

The command exits with code `1` if any check fails.

## nagare plugin build

Build and package the plugin in the current directory. See [Plugin overview](https://docs.nagare.smtdfc.net/en/plugins/overview.md#build-a-plugin-package).

```bash theme={null}
nagare plugin build [--sign <private-key.pem>]
```

| Option | Description |
| - | - |
| `-s`, `--sign <path>` | Sign the package with an Ed25519 private key (PEM). See [Plugin signing](https://docs.nagare.smtdfc.net/en/plugins/signing.md). |

## nagare-desktop

The desktop app is a separate executable, not a subcommand of `nagare`. See [Installation](https://docs.nagare.smtdfc.net/en/installation.md#desktop-app).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.