Auth

The rensei auth command manages named authentication contexts stored in ~/.config/rensei/config.json. Each context holds metadata (kind, org, name) while sensitive token material lives in a separate secret backend. You can have multiple contexts and switch between them without losing your active settings.

Context kinds

Secret backends

Token material is stored in one of four backends selected at auth add time:

Priority order when multiple sources are available: --token-stdin > keychain/encrypted_file > RENSEI_AUTH_TOKEN > RENSEI_API_TOKEN.

Commands

auth add

Add a new authentication context.

Browser login (recommended for humans):

rensei auth add --user

Opens the Rensei WorkOS login page in your browser. After completing the flow, a named context is created and activated.

Org API key (automation / CI):

printf '%s' "$RENSEI_TOKEN" | rensei auth add \
  --name ci-deploy \
  --kind org_token \
  --token-stdin

Project token (daemon registration):

printf '%s' "$RSP_TOKEN" | rensei auth add \
  --name daemon-prod \
  --kind project_token \
  --token-stdin

Pre-issued user JWT (CI environment with SSO):

printf '%s' "$RENSEI_JWT" | rensei auth add \
  --user \
  --name sso-bot \
  --token-stdin

Encrypted-file backend (headless Linux):

printf '%s' "$RENSEI_TOKEN" | rensei auth add \
  --kind org_token \
  --secret-store encrypted-file \
  --token-stdin

Set RENSEI_SECRET_PASSPHRASE in your environment so subsequent runs unlock the file without prompting.

auth list

List all stored contexts:

rensei auth list
rensei auth list --json

Example output:

NAME         KIND           ORG           ACTIVE
mark         user           acme-corp     ✓
ci-deploy    org_token      acme-corp
daemon-prod  project_token  acme-corp

auth show

Inspect a specific context (token material is never displayed):

rensei auth show ci-deploy

auth activate

Set the active context used by default for all CLI commands:

rensei auth activate ci-deploy

auth remove

Remove a context and delete its token from the secret backend:

rensei auth remove ci-deploy

Per-command context override

Use --auth to run a single command under a different context without changing the active one:

rensei --auth ci-deploy --org acme-corp fleet list

This is useful in scripts that need to operate as a service account while your interactive session uses a user context.

Multiple orgs

If you have access to multiple Rensei orgs, each context is scoped to the org it was created in. Switch orgs with --org <slug> or by activating a context from the target org:

rensei auth list           # see all contexts and their orgs
rensei --org other-org org show

Token rotation

User contexts are refresh-token backed. The CLI refreshes the access token silently in the background before it expires.

Org and project tokens (rsk_/rsp_) are long-lived API keys. Rotate them by creating a new key in the Rensei web app (Settings → API Keys), updating your context, then revoking the old key.

To update the token stored in an existing context:

rensei auth remove old-ci
printf '%s' "$NEW_TOKEN" | rensei auth add \
  --name old-ci \
  --kind org_token \
  --token-stdin

CI/CD patterns

- name: Add Rensei auth context
  env:
    RENSEI_TOKEN: ${{ secrets.RENSEI_API_TOKEN }}
  run: |
    printf '%s' "$RENSEI_TOKEN" | rensei auth add \
      --name ci \
      --kind org_token \
      --secret-store none \
      --token-stdin

export RENSEI_AUTH_TOKEN=rsk_live_...
rensei fleet list        # no auth add needed

Credential model

When auth add --user completes the WorkOS device flow, the CLI stores a WorkOS user access token. All API calls - including host install token minting, Linear proxy calls, and worker dispatch - are routed through the Rensei platform proxy using this credential. You never hand-spin worker credentials. The platform exchanges the user context for the appropriate scoped tokens server-side.

The same credential model applies to org_token contexts (rsk_live_*): the platform proxy handles credential injection and scope enforcement. Agents running on daemon workers receive platform-managed secrets through the credential socket at spawn time, not from your local shell environment.

Context activation and --org/--project flags

rensei auth activate, rensei activate, and rensei setup set the default context - the org and project used when a command is run without explicit flags. They are convenience helpers, not hard boundaries.

Every command also accepts --org <slug> and --project <slug> as persistent flags that override the default context for that invocation without changing it globally:

# Run against a different project without changing the active one
rensei --org my-org --project staging project list

# Activate a different context globally
rensei auth activate ci-context

This means activate/switch set a default, not a mandatory scope. Any command can target any org/project directly with the flags.

Related

• Global flags - --auth, --org, --project, --token-stdin
• Environment variables - RENSEI_AUTH_TOKEN, RENSEI_API_TOKEN, RENSEI_SECRET_PASSPHRASE
• API keys - creating and scoping rsk_live_... org keys