SessionBase CLI

CLI tool for SessionBase - manage and share AI coding sessions from Claude Code, Gemini CLI, Amazon Q Chat, and OpenAI Codex CLI.

Quick Start

For more detailed documentation, see docs.sessionbase.ai.

Installation

Install the SessionBase CLI globally:

npm install -g @sessionbase/cli

This provides two commands:

• sessionbase - Main CLI interface
• sb - Shorthand alias for faster typing
• sessionbase-mcp - MCP server for AI platforms

Authentication

Authenticate with your SessionBase account:

sessionbase login

This will open your browser to complete the authentication process with GitHub or Google.

Verify you're logged in:

sessionbase whoami

Push Your First Session

Note that all sessions are public and discoverable by default, unless you supply the --private flag. Private sessions are only visible to the owner of the session.

Push your most recent AI chat session from your current directory:

# From Claude Code
sessionbase push --claude

# From Gemini CLI (after saving with /chat save)
sessionbase push --gemini

# From Amazon Q Chat
sessionbase push --qchat

# From OpenAI Codex CLI
sessionbase push --codex

MCP Server Setup (Recommended)

The MCP server enables you to push sessions directly from your AI chat without breaking your workflow.

Claude Code

claude mcp add sessionbase sessionbase-mcp --scope user

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}

Amazon Q Chat

Add to ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.sessionbase]
command = "sessionbase-mcp"

Usage Examples

CLI Commands

# List all sessions
sessionbase ls --global

# Push private session with metadata
sessionbase push --claude --title "Debug Session" --tags "debugging,api" --private

# Push specific file
sessionbase push /path/to/session.json

MCP Server (Natural Language)

Once configured, use natural language in your AI chat:

• "Push this to SessionBase"
• "Push this session as private with the tags 'API debugging'"

Custom Slash Commands

Claude Code

mkdir -p ~/.claude/commands
echo "Use the sessionbase push_session tool to upload the current session" > ~/.claude/commands/upload.md

Now you can run /upload from Claude and it will automatically generate metadata and push to SessionBase. You can rename upload.md to create a different alias.

Gemini CLI

mkdir -p ~/.gemini/commands
touch ~/.gemini/commands/upload.toml

Add this content to ~/.gemini/commands/upload.toml:

description="Upload the current session to SessionBase"
prompt= """
Use the sessionbase push_session tool to upload the current session.

If you see a warning that the most recent session is outdated, ask the user to run `/chat save <tag>` to save a new checkpoint, then re-run /upload.
"""

Now you can run /upload from Gemini CLI to automatically push sessions to SessionBase.

Note: Amazon Q Chat and OpenAI Codex CLI do not currently support custom slash commands. Use natural language instead (e.g., "Push this to SessionBase").

Platform Support

| Platform | Local Storage | SessionBase Access | |----------|----------------|-------------------| | Claude Code | Stores all session files automatically | Can push current session or list/choose from directory | | Gemini CLI | Only stores if you use /chat save | Can push saved sessions and list/choose from directory | | Amazon Q Chat | Only stores most recent session per directory | Can detect and push current session automatically | | OpenAI Codex CLI | Stores all session files automatically | Can push current session or list/choose from directory |

Troubleshooting

"No such file or directory" Error

Ensure the package is installed globally:

npm install -g @sessionbase/cli
which sessionbase-mcp  # Should show the binary path

Authentication Issues

Verify you're logged in:

sessionbase whoami

If not authenticated, run sessionbase login again.

Development

Setup

# Install dependencies
npm install

# Build the CLI
npm run build

# Link globally for testing
npm link

# Verify installation
sessionbase --help
sessionbase --version

Unlink (when done testing)

npm unlink -g