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

# Command line (CLI)

> Install the nuphos CLI, sign in from any machine (including headless servers and bots), and drive Nuphos from scripts.

`nuphos` is a terminal client for Nuphos. Without a command it opens an
interactive TUI. Every TUI action is also a command, so scripts and other agents
can use Nuphos too.

## Install

```bash theme={null}
curl -fsSL https://nuphos.ai/install | sh
```

The script installs the latest release for macOS or Linux (x86\_64 or arm64)
into `~/.local/bin`. If that directory is not on your `PATH`, the installer
prints the exact line to add to your shell profile, for example:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

Run `nuphos update` later to install the newest release over the binary.

## Sign in

```bash theme={null}
nuphos login
```

`nuphos login` picks the first method that works:

1. **Nuphos Desktop:** if the desktop app is signed in on this machine, the CLI
   uses that sign-in.
2. **Browser:** if this machine can open a browser, it signs you in with Google.
3. **Device code:** on a headless server, over SSH, or in a container, the CLI
   prints a short code instead. Use `--device` to choose this even when a
   browser is available.

```bash theme={null}
nuphos login --device
```

```text theme={null}
To sign in, open https://nuphos.ai/device on any device and enter:

    WDJB-MJHT

Only enter it there yourself; never approve a code someone sent you.
Waiting for approval…
```

Open [nuphos.ai/device](https://nuphos.ai/device) on your laptop or phone,
enter the code, and choose how to sign the terminal in:

* **As me:** the terminal acts as you, in all your teams.
* **As an agent:** the terminal signs in as a named bot (for example "Grok Bot")
  that works in **one team** you pick. See [Agent tokens](#agent-tokens).

The CLI finishes signing in by itself. The code expires after 10 minutes and
works once.

> [!WARNING]
>
> Only approve a code from a terminal you started yourself. Anyone who gets you
> to approve their code gets access to your account.

Check or end the session:

```bash theme={null}
nuphos auth status   # who is signed in, and where the token is kept
nuphos logout        # sign the CLI out (Nuphos Desktop stays signed in)
```

On macOS the token is kept in the Keychain. Elsewhere it is stored in
`~/.config/nuphos/cli.yaml`, readable only by your user (mode `0600`).

## Agent tokens

An agent token lets a bot or automation use Nuphos under its own name, on
your behalf. Messages it sends show as **"Grok Bot · via Ada Lovelace"** on
Desktop and iOS, not as your own words.

An agent token:

* works in one team only;
* can do in that team what you can do, except manage tokens, approve device
  codes, change your account or profile, manage members and roles, or change
  billing;
* is recorded as the sender of every message it posts, so you can tell what it
  did.

There are two ways to get one:

* **From the machine itself:** run `nuphos login --device` there and choose
  **As an agent** on the approval page. Nothing needs to be copied.
* **By hand:** create one in [nuphos.ai/settings/tokens](https://nuphos.ai/settings/tokens).
  The token is shown once. Hand it to the bot without putting it in shell
  history:

  ```bash theme={null}
  nuphos login --token - < token.txt
  ```

  or set it for one process only, without saving it:

  ```bash theme={null}
  NUPHOS_CLI_TOKEN=nup_… nuphos exec "Post the nightly build status"
  ```

Agent tokens can only be created from a browser sign-in, so a CLI token can
never create more tokens.

## Review and revoke

[nuphos.ai/settings/tokens](https://nuphos.ai/settings/tokens) lists every
terminal signed in with a device code and every agent token: name, kind, team,
created and last used. **Revoke** signs it out immediately. Browser and desktop
sign-ins are not listed.

From a personal CLI sign-in:

```bash theme={null}
nuphos token list
nuphos token revoke <id>
```

Changing your password revokes all of them.

## Common commands

| Command | What it does |
| - | - |
| `nuphos` | Open the interactive TUI |
| `nuphos exec "PROMPT"` | Send a message and print the reply. Reads stdin when there is no prompt. Add `--session <id>` to continue a conversation |
| `nuphos conversations [QUERY]` | List recent conversations, or find them by a word in the title or first message |
| `nuphos resume [SESSION]` | Open the TUI on a conversation, or pick one |
| `nuphos team [NAME]` | List teams or switch the default team |
| `nuphos agents` | List the agents conversations run on, and pick one for new conversations |
| `nuphos model` | Show or set a conversation's model and reasoning effort |
| `nuphos stop --session <id>` | Stop the reply in progress |

Add `--json` to any command for machine-readable output, and `--team <id or name>`
to target a team other than the last one used.

## Environment variables

| Variable | Purpose |
| - | - |
| `NUPHOS_CLI_TOKEN` | Use this token instead of the saved sign-in, without saving it |
| `NUPHOS_TEAM` | Default team id or name |
| `NUPHOS_API_URL` | API endpoint, for self-hosted Nuphos |


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