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