The Selective CLI, sel: stream live test results from your CI builds to your
terminal or your agent.
With the install script, which puts sel in /usr/local/bin, or
~/.local/bin when that isn't writable (set INSTALL_DIR to choose):
curl -fsSL https://raw.githubusercontent.com/selectiveci/selective-cli/main/install.sh | shOr build from source with Go 1.23+: go build -o sel ./cmd/sel.
sel auth loginThis prints a one-time code and the URL, and opens your browser to it; approve
the request there and you're logged in. It opens the browser from an agent's
shell too (Claude Code's !, a background command). It doesn't open one over
SSH, in CI, or on Linux without a display; open the printed URL on any machine
where you're signed in to Selective. --no-browser or SELECTIVE_NO_BROWSER=1
turns it off, and $BROWSER picks the program (and opens over SSH).
It's the OAuth 2.0 device authorization grant (RFC 8628), the same flow as
gh auth login.
- Where the token lives. In your system keychain (macOS Keychain, Linux
Secret Service, Windows Credential Manager). Without one, it goes in
~/.config/selective/config.jsonwith mode 0600, and the CLI says so. - Revoking it. It appears on your API tokens page as
"CLI: selective-cli on ", where you can revoke it.
sel auth logoutrevokes it too. - Other servers. Use
--hostname:sel auth login --hostname staging.selective.ci, or--hostname localhost:4000for a local dev server (loopback hosts default to http).
sel auth status # who you're logged in as, and whether the token still works
sel auth logout # revoke this machine's token and forget itDon't log in: 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. The runner gems' wss:// form works too. |
SELECTIVE_CONFIG_DIR |
Where to keep config (default ~/.config/selective). |
To store a token non-interactively, pass it on stdin. It never goes on the
command line, where it would land in shell history and ps.
sel auth login --with-token < token.txtWhat an agent (or you) needs to put a repository on Selective, without opening the dashboard:
sel auth signup # new account: signup page, then logged in with setup access
sel auth login --setup # existing account; also allows creating suites
sel orgs # your organizations (pass --org when you have several)
sel repos # repositories Selective's GitHub App can see
sel suites create --name web-rspec --framework rspec # repo defaults to this checkout's origin
sel suites key web-rspec --github-secret SELECTIVE_API_KEY- For agents.
sel auth login --setup --jsonwrites{"event":"authorize","url":…,"user_code":…,"browser_opened":…}to stdout at once and{"event":"logged_in",…}the moment the person approves. Run it in the background and wait for the second line.browser_openedsays whether a browser was launched; tell the person to look for the tab, and give them the URL either way. Without an account, the page signs them up with GitHub first. suites createis repeatable. The same name returns the same suite. Names are unique within an organization, so include the repository in the name when the organization has several.- The API key is never shown.
suites keyneeds a destination: a GitHub Actions secret throughgh(key on stdin) with--github-secret NAME, or--stdoutpiped into a secret store:sel suites key web-rspec --stdout | <your CI's secret command>.--stdoutrefuses a terminal. Either way it confirms the key wasn't displayed. - What a suite key can do. It only lets test runners join that suite's runs and report results. It can't read your code, your account, other suites or GitHub. If one leaks, rotate it on the suite's settings page.
- Output. JSON when piped or with
--json, tables on a terminal. SELECTIVE_ORGsets the organization for these commands.
sel tail # the build for this repo's HEAD commit
sel tail --run-id <id> # a specific buildOutput is NDJSON when piped and readable when on a terminal
(--format ndjson|pretty). Exit codes:
| Code | Meaning |
|---|---|
| 0 | all tests passed |
| 1 | real test failures |
| 2 | passed, but a test failed before passing on retry |
| 3 | no build found for this commit |
| 4 | authentication or network error |