`rbtk context` and `rbtk auth`

Two small groups, separated because they answer different questions:

rbtk auth — who am I, and how does the CLI prove it?
rbtk context — which org and project should this invocation act on?

rbtk org and rbtk project are read-only helpers that live alongside them.

rbtk auth
├── login                   # OAuth + keyring (interactive)
├── logout                  # Clear keyring + cached tokens
├── status                  # Who am I, what auth source, what token expiry
├── oidc-from-github        # GitHub OIDC token exchange
└── keys
    ├── list
    └── revoke

rbtk context
├── (default)               # Show current
├── set                     # Set org / project
├── list                    # List orgs and projects
└── clear                   # Wipe saved context

rbtk org
├── list
└── get

rbtk project
├── list
└── get

Interactive browser OAuth. Refresh token lands in the OS keyring.

rbtk auth login
# Browser opens at https://app.roboticks.io/cli/authorize?code=...

Headless? The CLI falls back to a one-time code:

Open this URL on a device with a browser:
  https://app.roboticks.io/cli/authorize?code=GZHF-QXAQ
Then return here.

Flag	Description
`--no-browser`	Force the headless flow even on a desktop
`--device <name>`	Friendly device name for the audit log

`rbtk auth logout`

rbtk auth logout
# Cleared refresh token from keyring.
# Note: API keys in env vars are still active (this command only clears keyring auth).

`rbtk auth status`

rbtk auth status

USER       amir@roboticks.io (org: acme, role: owner)
SOURCE     OS keyring (refresh token expires in 14 days)
TOKEN      access token expires in 58m, will auto-refresh
ORG        acme (Team)
PROJECT    warehouse
PLATFORM   https://api.roboticks.io (us-east-1)
CLI        v1.4.0

--output json returns the same as a record (handy for jq in scripts).

`rbtk auth oidc-from-github`

Inside a GitHub Actions job, this trades the GH-provided OIDC token for a CLI access token. No long-lived secret required.

permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@v4
  - run: pipx install roboticks-cli
  - run: rbtk auth oidc-from-github
  - run: rbtk test run --push ./

The exchanged token is cached in memory for the rest of the workflow. See Authentication → GitHub OIDC for the subject-claim policy setup.

`rbtk auth keys list`

rbtk auth keys list

NAME                    SCOPE             CREATED       LAST USED       EXPIRES
gitlab-ci-warehouse     project:warehouse 2026-04-12    2 minutes ago   2026-07-11
audit-bot               org:acme:admin    2026-01-08    13 hours ago    never

Flag	Description
`--include-expired`	Also show expired keys
`--scope project\|org`	Filter

`rbtk auth keys revoke`

rbtk auth keys revoke rbtk_sk_xx... --confirm

Effect is immediate; any in-flight HTTP request using the key fails with 401. The audit log records the actor.

`rbtk context` (default)

Show the active org and project. This is what every other command uses unless overridden by --org / --project.

rbtk context
# Org:     acme (Team)
# Project: warehouse

`rbtk context set`

rbtk context set --org acme --project warehouse
rbtk context set --project robot-firmware       # keep current org

The selection persists in ~/.config/roboticks/context.yaml (or %APPDATA%\roboticks\context.yaml on Windows).

Repo-local context

If a .roboticks/context.yaml file exists in the current directory (or any parent), it takes precedence over the user-level setting. Commit it to your repo so every contributor lands in the right org/project automatically:

# .roboticks/context.yaml
org: acme
project: warehouse

`rbtk context list`

List orgs and projects you can access.

rbtk context list

ORG     PROJECTS
acme    warehouse, api, robot-firmware
zenith  pilot

--output json returns the same as a structured tree.

`rbtk context clear`

rbtk context clear
# Cleared user-level context. Repo-local context (if any) still applies.

`rbtk org list` and `rbtk org get`

rbtk org list
rbtk org get acme            # specific
rbtk org get                 # current org

get shows tier, seats, included sim minutes, current month’s burn-down, and SSO config.

`rbtk project list` and `rbtk project get`

rbtk project list
rbtk project get warehouse

get shows linked GitHub repos, requirement baselines, pinned standards, and routing flags (airgapped, hosted_fallback).

Common patterns

# Run a quick command in a non-default org/project without switching context
rbtk --org zenith --project pilot test list

# Drop a context file into a freshly-cloned repo
mkdir -p .roboticks
cat > .roboticks/context.yaml <<EOF
org: acme
project: warehouse
EOF
git add .roboticks/context.yaml && git commit -m "Pin Roboticks context"

Authentication deep-dive

OAuth, API keys, GitHub OIDC — when to use each.

Test commands

The biggest command group.

rbtk context & auth

`rbtk context` and `rbtk auth`

`rbtk auth logout`

`rbtk auth status`

`rbtk auth oidc-from-github`

`rbtk auth keys list`

`rbtk auth keys revoke`

`rbtk context` (default)

`rbtk context set`

Repo-local context

`rbtk context list`

`rbtk context clear`

`rbtk org list` and `rbtk org get`

`rbtk project list` and `rbtk project get`

Common patterns

Next

Authentication deep-dive

Test commands

Documentation Index

​rbtk context and rbtk auth

​rbtk auth login

​rbtk auth logout

​rbtk auth status

​rbtk auth oidc-from-github

​rbtk auth keys list

​rbtk auth keys revoke

​rbtk context (default)

​rbtk context set

​Repo-local context

​rbtk context list

​rbtk context clear

​rbtk org list and rbtk org get

​rbtk project list and rbtk project get

​Common patterns

​Next

Authentication deep-dive

Test commands

`rbtk context` and `rbtk auth`

`rbtk auth login`

`rbtk auth logout`

`rbtk auth status`

`rbtk auth oidc-from-github`

`rbtk auth keys list`

`rbtk auth keys revoke`

`rbtk context` (default)

`rbtk context set`

Repo-local context

`rbtk context list`

`rbtk context clear`

`rbtk org list` and `rbtk org get`

`rbtk project list` and `rbtk project get`

Common patterns

Next