Session Management Playbook

Manage CLI sessions, profiles, and environment switching.

Understanding Sessions

Sessions are tenant-keyed -- each profile has its own session. Configuration priority (highest to lowest):

1. --profile CLI flag
2. SYSTEMPROMPT_PROFILE environment variable
3. Active session from .systemprompt/sessions/index.json
4. Default profile

Session Storage

Sessions are stored in .systemprompt/sessions/index.json:

{
  "version": 1,
  "sessions": {
    "local": {
      "tenant_key": "local",
      "profile_name": "local",
      "profile_path": "/path/to/.systemprompt/profiles/local/profile.yaml",
      "session_token": "eyJ...",
      "user_email": "admin@local.dev",
      "user_type": "admin",
      "expires_at": "2026-02-02T10:00:00Z"
    }
  },
  "active_key": "local"
}

Session Expiration

Sessions expire 24 hours after creation. When expired, re-authenticate with just login.

Check Current Session

{ "command": "admin session show" }

List Available Profiles

{ "command": "admin session list" }

Switch Profile

Switch to a different profile (automatically loads corresponding session):

{ "command": "admin session switch <profile-name>" }

Login and Logout

Login and logout are terminal operations (not MCP):

just login
just login production
just logout

Login creates cloud credentials at .systemprompt/credentials.json. Sessions expire after 24 hours by default.

Troubleshooting

Note: All other playbooks should cross-reference this section for authentication issues.

Quick Reference