The selective CLI

The selective CLI streams live results from your CI builds to your terminal or to a coding agent. It is separate from the Ruby runner, which is what runs inside CI.

Install

curl -fsSL https://raw.githubusercontent.com/selectiveci/selective-cli/main/install.sh | sh

Or build from source with Go 1.23 or later: go build -o selective ./cmd/selective in a clone of selectiveci/selective-cli.

Log in

selective auth login

This prints a one-time code and opens your browser. Approve the request there and you’re logged in. With no browser available (SSH, containers), it prints the URL to open on any machine where you’re signed in. It’s the OAuth 2.0 device authorization grant, the same flow as gh auth login.

Command	What it does
`selective auth login`	Log in through the browser.
`selective auth login --no-browser`	Print the URL instead of opening a browser.
`selective auth login --with-token < token.txt`	Store an API token read from stdin.
`selective auth login --hostname staging.selective.ci`	Log in to a different server. Loopback hosts default to `http`.
`selective auth status`	Who you’re logged in as, and whether the token still works.
`selective auth logout`	Revoke this machine’s token and forget it.

The token is stored in your system keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager). Without one it goes in ~/.config/selective/config.json with mode 0600, and the CLI tells you so. It appears on your API tokens page as CLI: selective-cli <version> on <hostname>, where you can revoke it.

Tokens for CI and agents

Don’t log in interactively. Create a token on the API tokens page and provide it through the environment:

Variable	Meaning
`SELECTIVE_TOKEN`	API token to use. Takes precedence over any stored login and is never written to disk.
`SELECTIVE_HOST`	Server, when it isn’t `app.selective.ci`.
`SELECTIVE_CONFIG_DIR`	Where to keep config. Default `~/.config/selective`.

Pass a token on stdin, never on the command line, where it would land in shell history and ps.

Tail a build

selective tail                    # the build for this repo's HEAD commit
selective tail --run-id <id>      # a specific build
selective tail --commit <sha>     # the build for another commit
selective tail --format ndjson    # force machine-readable output

Output is readable on a terminal and NDJSON when piped (--format ndjson|pretty overrides). Events are build_start, test_pass, test_fail and summary, one JSON object per line.

Exit codes

Code	Meaning
`0`	All tests passed.
`1`	Real test failures.
`2`	Only flaky failures: every failure passed on retry.
`3`	No build found for this commit.
`4`	Authentication or network error.

The exit code is the whole point for scripts and agents: selective tail && deploy waits for the run and only proceeds on green, and 2 lets you treat a flaky-only run differently from a real failure.