Skip to main content
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

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:
Run nuphos update later to install the newest release over the binary.

​
Sign in

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.
Open 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.
The CLI finishes signing in by itself. The code expires after 10 minutes and works once.
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:
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. The token is shown once. Hand it to the bot without putting it in shell history:
    or set it for one process only, without saving it:
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 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:
Changing your password revokes all of them.

​
Common commands

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