CLI reference

Source: github.com/gentityapp/cli. Install with curl -fsSL https://gentity.ai/install.sh | bash or brew install gentityapp/tap/gentity.

Every command falls back to environment variables when flags are omitted — handy for CI where you don't want to touch the filesystem.

Global

Command	What it does
`gentity --version`	Print the installed version.
`gentity --help`	Top-level command list.
`gentity compute --help`	Per-subcommand help.

Environment

Variable	Default	Purpose
`GENTITY_TOKEN`	—	Override the saved token. Set this in CI.
`GENTITY_API_URL`	`https://gentity.ai`	Point at a non-prod control plane.
`ANTHROPIC_API_KEY` /`OPENAI_API_KEY` /`OPENROUTER_API_KEY` / etc.	—	Picked up by `compute create` when you omit `--api-key`.
`NO_COLOR`	—	Disable ANSI color in output.

`gentity login`

Store an API token locally.

gentity login [--token <gn_live_...>] [--api-url <url>]

With no flags, the CLI reads from stdin. The token is verified by calling a protected endpoint before being saved — a bad token is never written to disk.

`gentity logout`

Clear the stored token. The config file is kept (with token=null) so any custom apiUrl stays in place.

`gentity agents`

List the agent catalog. No auth required.

gentity agents          # human-readable
gentity agents --json   # full structured data (use with jq)

`gentity compute create`

gentity compute create \
  --agent <id> --model <name> \
  [--api-key <key>] [--name <label>] [--region <code>] [--detach]

Flag	Required	What it does
`--agent`	yes	Agent id from the catalog (`gentity agents`).
`--model`	yes	Model name (e.g. `claude-sonnet-4-5`).
`--api-key`	—*	Provider API key. *Required if the matching env var (e.g. `ANTHROPIC_API_KEY`) is unset.
`--name`	—	Display label. Defaults to `<Agent> - <model>`.
`--region`	—	Fly region code. Default `sjc`. Supported: `sjc lax sea iad ewr ord nrt hkg sin syd fra ams lhr`.
`--detach`	—	Return as soon as the row is created; don't poll for `running`.

`gentity compute list`

Table or JSON of your instances.

gentity compute list
gentity compute list --json | jq '.[] | select(.status == "running")'

`gentity compute start|stop|restart <id>`

Lifecycle transitions. Block until Fly confirms. id accepts the full cuid, an unambiguous prefix, or the subdomain.

`gentity compute delete <id>`

Destroy the machine and the persistent volume. Asks for confirmation by typing the id back; pass --yes in CI.

`gentity compute open <id>`

Open https://<subdomain>.gentity.ai/ in the default browser. In non-TTY contexts (CI, piped output) just prints the URL.

`gentity compute logs <id>`

gentity compute logs <id> [--lines N] [--follow] [--json]

Default: last 200 lines of the container, pretty-printed with timestamp + level. --follow streams via Server-Sent Events until you Ctrl-C. --json dumps the raw flyctl JSON shape.

`gentity compute ssh <id>`

Open an interactive shell inside the instance's container. Pipes local raw-mode stdin to a remote PTY via WebSocket, with SIGWINCH forwarded for terminal resize.

Requires a real TTY — refuses to run with redirected stdin.

`gentity completion <shell>`

Print a shell-completion script. Supported: bash, zsh, fish.

# Per-session
source <(gentity completion bash)
source <(gentity completion zsh)
gentity completion fish | source

# Permanent
gentity completion zsh > "${fpath[1]}/_gentity"
gentity completion fish > ~/.config/fish/completions/gentity.fish

Homebrew users get all three installed automatically.