<!-- Source: https://console.uubright.com/docs/cli/ -->
# Command line

## The `uubright` command

The server’s command is `uubright`, or `uub` for short. Some installed
packages also expose the older command names `scimigo` and `ccr-cloud`.
Run `uubright --help` to list commands. Setup, pairing, and relay sign-in
commands below apply to server packages that include those tools.

## Workspaces

Run as the uuBright Console service user, with the same `CCR_CLOUD_DATA` as the server:

```sh
npm run workspace -- list
npm run workspace -- create "Coding"
npm run workspace -- set-identity w-... "Your Name" you@example.com
npm run workspace -- login-github w-...
npm run workspace -- login-claude w-...
npm run workspace -- login-codex w-...
npm run workspace -- use-host-login w-... claude
npm run workspace -- use-host-login w-... codex
npm run workspace -- enable-plugin w-... /absolute/path/to/plugin
npm run workspace -- disable-plugin w-... /absolute/path/to/plugin
npm run workspace -- set-instructions w-... --stdin < instructions.txt
npm run workspace -- set-manager w-... s-...      # or --clear; see Manager
npm run workspace -- set-mode w-... work          # move a chat workspace (being retired) to work mode
npm run workspace -- set-attachment-limits default 50 200   # MB per file, MB per message
npm run workspace -- set-attachment-limits w-... --default
# Or supply a token on stdin from a private source:
npm run workspace -- set-github w-... --token-stdin
```

The `uubright` command accepts the same commands as `uubright workspace ...`.
The token command reads standard input; tokens never belong in command arguments.
`login-github` opens `gh auth login` with that workspace's private `GH_CONFIG_DIR`.
Named workspaces use the host agent logins until you opt in to separate logins.
`login-claude` and `login-codex` open the configured `CLAUDE_BIN` or `CODEX_BIN`
(falling back to `claude` or `codex`) with the selected workspace's private home;
on success they select `own` mode for that agent. `use-host-login` selects the
host login again without copying credentials. The plugin commands update
the enabled directory list; Codex skills and MCP config are refreshed at task
start. `set-instructions` reads text from standard input. `set-manager` sets
or clears the workspace's [Manager](https://console.uubright.com/docs/manager/). `enable-plugin` prints
and saves the canonical plugin path, including for a symlinked parent.
`set-attachment-limits` changes how large [attached files](https://console.uubright.com/docs/tasks/#attach-files) can be
in that workspace (25 MB per file and 100 MB per message by default); it works for
`default` too, takes effect on the next upload, and is the only way to change them.
Stopped tasks use the workspace's current login mode, plugin list and
instructions when started again. A plugin MCP setting that cannot be
translated for Codex fails task preparation with a named error.
See [Workspaces](https://console.uubright.com/docs/workspaces/).

In the app, **New workspace…** in the workspace switch (or More on a phone) does `create`, `set-identity`
and, with the owner token, `enable-plugin` in one step, and Workspace settings renames a workspace and
changes its Git identity and, with the owner token, plugins ([API](https://console.uubright.com/docs/api/#workspaces)). The sign-in commands (`login-claude`,
`login-codex`, `login-github`, `set-github`, `use-host-login`), `set-instructions`, `set-attachment-limits` and the
plugin commands for paired devices stay here. There is no command to delete a workspace yet.


Run these from the installed server package **on the server, as the service user**.
Workspace credential commands explicitly change only that workspace's private
configuration; the other commands do not change your Claude or Git credentials.

## `npm run setup`

Prepares configuration and prints the next steps. Safe to run again: it keeps your
existing configuration and owner token.

```sh
npm run setup -- [options]
```

| Option | Effect |
|---|---|
| (none) | Create or check configuration and print connection steps. |
| `--start` | Also start the service in tmux if it isn't running, then verify it accepts your token. Never restarts a running service. |
| `--tailscale` | Publish the app on your tailnet with Tailscale Serve. See [Tailscale](https://console.uubright.com/docs/remote-access/#tailscale). |
| `--cloudflare HOSTNAME` | Set up a Cloudflare tunnel for your hostname. See [Cloudflare](https://console.uubright.com/docs/remote-access/#cloudflare). |
| `--verbose` | Show logs, configuration paths and optional GitHub checks. |
| `--anthropic-key-stdin` | Check and save an Anthropic API key read from standard input. |
| `--bedrock-region REGION` | Check and save AWS Bedrock in that region, with `--aws-profile NAME` (default `default`) or `--aws-access-key-id ID --aws-secret-stdin` (secret, then an optional session token, on standard input). |
| `--ccr-url URL --ccr-key-stdin` | Check and save a Claude Code Router gateway and its client key, read from standard input. |
| `--no-check` | With a model option, save without the live check. |
| `--help` | Show help without changing anything. |

The model options are described in [Bring your own model](https://console.uubright.com/docs/bring-your-own-model/#connect-with-setup).
Without one, setup says which model new tasks use, or warns that none is connected.

## `npm run doctor`

Checks tools and host resources without changing anything. It checks that `claude`
exists and says which model new tasks use: the one connected under
[Bring your own model](https://console.uubright.com/docs/bring-your-own-model/), a CCR gateway in `server.env`, or
Claude Code's own login. It doesn't send a model request; use a scratch task or
`claude -p "Reply OK"` for that.

```sh
npm run doctor                # tools and resources
npm run doctor -- --service   # also check the running service
```

## `npm run github`

Diagnoses Git and GitHub access without printing credentials. See
[Set up GitHub access](https://console.uubright.com/docs/repositories/#set-up-github-access).

| Command | Effect |
|---|---|
| `npm run github` | Check commit identity, GitHub API login and SSH authentication. |
| `npm run github -- --repo URL` | Check one exact repository URL. Exits with 1 if it can't be read or Git has no commit identity. |
| `npm run github -- --setup --protocol ssh` | Print SSH setup steps. |
| `npm run github -- --setup --protocol https` | Print HTTPS credential-helper setup steps. |

Push access is never tested. Results apply to the shell you run them in, which can
differ from a running service; confirm in the app afterwards.

## `npm run pair`

Prints a one-time link (and a QR code, if `qrencode` is installed) that signs a phone in
without the access token. The service must be running. See
[Sign in on your phone](https://console.uubright.com/docs/remote-access/#sign-in-on-your-phone).

`npm run pair -- --relay` instead prints a one-time link through the configured
relay. Sign the host in to the relay and restart the service first. Paste that
link under **Server settings → Add a computer** in another console window, or
open it in the phone app. Use a fresh link for each device; each lasts ten
minutes and works once. Without `--relay`, `npm run pair` keeps printing a
direct link for the server's own address.

## `npm run relay`

`npm run relay -- login|status|logout` signs a server host in to the
[uuBright relay](https://console.uubright.com/docs/relay-managed/). `login` prompts for the password (or reads it
with `--password-stdin`) and saves a revocable host token in `relay-account.json`
in the data directory; restart the service afterwards. `logout` revokes the token
and removes the file (`--local-only` only removes it). `status` shows the account,
plan and whether this host is registered. `tokens` asks for the password (a host
token can manage only its own host), lists every host sign-in on the account, and
with `--revoke ID` revokes one, for example an old machine's.

## `npm run resources`

Prints a read-only snapshot of memory, swap, load, disk and inodes, then how many
tasks the host can run at once and the risks to watch. See
[Check host resources](https://console.uubright.com/docs/operations/#check-host-resources) and [Capacity](https://console.uubright.com/docs/operations/#capacity).

## `npm run image`

Builds the Docker session image. Needed only for [Docker mode](https://console.uubright.com/docs/docker/).

## `npm start`

Starts the control plane in the foreground with settings from the environment. Setup
uses a start script that loads `server.env` first, so prefer
`npm run setup -- --start` in host mode.

## `npm run dev`

Starts a development server at http://localhost:8790 (token `dev`) with a fake
Claude, so you can try the app without model access. It keeps its data in
`.data/dev` and ignores your real `CCR_CLOUD_DATA` and `CCR_CLOUD_TOKEN`. Prompts
starting with `use-tool` trigger an approval request.

## Output

When attached to a terminal, output uses colored `OK`, `WARN`, `FAIL` and `INFO`
labels. The labels stay readable without color. Set `NO_COLOR=1` to turn color off
or `FORCE_COLOR=1` to force it.

## Personal WeChat (experimental)

`npm run wechat -- login|status|logout|unlock` manages local pairing. Use
`login --replace` to re-pair. Stop the API before changing pairing or clearing a
lock. See [Personal WeChat](https://console.uubright.com/docs/wechat/).

## Personal WhatsApp (experimental)

`npm run whatsapp -- login|status|logout|unlock` manages QR pairing and local state.
Stop the API before login/logout/unlock. See [Personal WhatsApp](https://console.uubright.com/docs/whatsapp/).
