> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# rbtk context & auth

> Reference for rbtk context and rbtk auth — switching org/project, login, logout, status, keys, GitHub OIDC exchange.

# `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
```

## `rbtk auth login`

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

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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.**

```yaml theme={null}
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](/cli/authentication#github-oidc-github-actions) for the subject-claim policy setup.

## `rbtk auth keys list`

```bash theme={null}
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`

```bash theme={null}
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`.

```bash theme={null}
rbtk context
# Org:     acme (Team)
# Project: warehouse
```

## `rbtk context set`

```bash theme={null}
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:

```yaml theme={null}
# .roboticks/context.yaml
org: acme
project: warehouse
```

## `rbtk context list`

List orgs and projects you can access.

```bash theme={null}
rbtk context list

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

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

## `rbtk context clear`

```bash theme={null}
rbtk context clear
# Cleared user-level context. Repo-local context (if any) still applies.
```

## `rbtk org list` and `rbtk org get`

```bash theme={null}
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`

```bash theme={null}
rbtk project list
rbtk project get warehouse
```

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

## Common patterns

```bash theme={null}
# 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"
```

## Next

<CardGroup cols={2}>
  <Card title="Authentication deep-dive" icon="key" href="/cli/authentication">
    OAuth, API keys, GitHub OIDC — when to use each.
  </Card>

  <Card title="Test commands" icon="flask-vial" href="/cli/test-commands">
    The biggest command group.
  </Card>
</CardGroup>