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/session.json
  4. Default profile

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

Issue Solution
No valid session Re-login via terminal: just login
Not authenticated Re-login via terminal: just login
Wrong profile active List with admin session list, switch with admin session switch <name>
Session expired Sessions expire after 24 hours. Re-authenticate: just login
Permission denied Check profile has required permissions: admin session show
Connection failed Check credentials exist in .systemprompt/credentials.json

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

Quick Reference

Task Method Command
Check session MCP admin session show
List profiles MCP admin session list
Switch profile MCP admin session switch <name>
Login Terminal just login
Logout Terminal just logout