# Installation
Source: https://docs.sessionbase.ai/cli/installation

Install and set up the SessionBase CLI

## Prerequisites

* **Node.js 18+**: The CLI requires Node.js version 18 or higher
* **npm**: Comes bundled with Node.js
* **AI Agent Platform**: One or more of:
  * [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
  * [Gemini CLI](https://github.com/google-gemini/gemini-cli)
  * [Amazon Q Chat](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html)
  * [OpenAI Codex CLI](https://developers.openai.com/codex/cli)

## Install the CLI

### Global Installation (Recommended)

Install the SessionBase CLI globally to access it from anywhere:

```bash
npm install -g @sessionbase/cli
```

This provides two commands:

* `sessionbase` - Main CLI interface
* `sessionbase-mcp` - MCP server for AI platforms

### Verify Installation

Confirm the installation was successful:

```bash
sessionbase --version
sessionbase --help
```

`sb` - Shortcut for `sessionbase`

## Authentication

After installation, authenticate using:

```bash
sessionbase login
```

This will:

1. Open your browser to the SessionBase login page
2. Allow you to sign in with GitHub or Google
3. Provide an authentication token to copy into your terminal

### Manual Token Authentication

If you are already logged in to SessionBase in your browser, you can access your authentication token at [https://www.sessionbase.ai/settings](https://www.sessionbase.ai/settings) and provide the token directly:

```bash
sessionbase login --token YOUR_TOKEN_HERE
```

## Verify Authentication

Check that you're logged in successfully:

```bash
sessionbase whoami
```

This displays your username and authentication status.

## Next Steps

The SessionBase CLI is intended for consumption by AI agents via the SessionBase MCP server. While you can use the CLI directly, we recommend using the SessionBase MCP server directly from your AI agent of choice. This allows you to push sessions with rich contextual descriptions directly from Claude Code, Gemini CLI, Q Chat, or Codex CLI without breaking your workflow.

See our [MCP Server guide](/mcp-server/installation) for MCP installation instructions.

### Power User Tips

If you prefer to use the CLI, use the `sb` alias for faster typing:

```bash
sb push --claude --title "Debug Session"
sb list --global
```

You can also use SessionBase CLI commands directly from within some AI chat agents using the `!` operator (supported by Claude Code, Gemini CLI, and Amazon Q Chat):

```bash
# Push current session from within Claude Code
!sb push --claude --title "Current debugging session"

# List recent sessions
!sb list --claude

# Check authentication status
!sb whoami
```

This allows you to push sessions without leaving your AI conversation, even if you haven't set up the MCP server.


# Usage
Source: https://docs.sessionbase.ai/cli/usage

The SessionBase CLI provides commands to list, push, and manage AI chat sessions from Claude Code, Gemini CLI, Amazon Q Chat, and OpenAI Codex CLI.

## Available Commands

### `sessionbase ls`

List local chat sessions from all supported platforms.

```bash
# List all sessions from current directory
sessionbase ls

# List sessions from all projects globally
sessionbase ls --global

# Filter by specific platform
sessionbase ls --claude
sessionbase ls --gemini
sessionbase ls --qchat
sessionbase ls --codex

# List sessions from specific directory
sessionbase ls --path /path/to/project
```

**Options:**

* `--claude` - Show only Claude Code sessions
* `--gemini` - Show only Gemini CLI sessions
* `--qchat` - Show only Amazon Q Chat sessions
* `--codex` - Show only OpenAI Codex CLI sessions
* `--global` - Include sessions from all projects
* `--path <path>` - Filter sessions by specific directory

### `sessionbase push`

Push a chat session to SessionBase for sharing.

```bash
# Push most recent session from current directory
sessionbase push --claude
sessionbase push --gemini
sessionbase push --qchat
sessionbase push --codex

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

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

**Arguments:**

* `[file]` - Path to session file (.json or .jsonl) - mutually exclusive with platform flags

**Options:**

* `--claude` - Auto-detect most recent Claude Code session
* `--gemini` - Auto-detect most recent Gemini CLI session
* `--qchat` - Auto-detect most recent Amazon Q Chat session
* `--codex` - Auto-detect most recent OpenAI Codex CLI session
* `--private` - Make the session private. Private sessions are only visible to you.
* `--title <title>` - Set session title
* `--tags <tags>` - Comma-separated tags
* `--summary <summary>` - Session summary/description

**Notes:**

* **Upsert semantics:** If you push a session, continue chatting, then push again, SessionBase will update the existing session rather than creating a duplicate.

### `sessionbase login`

Authenticate with your SessionBase account.

```bash
# Interactive login (opens browser)
sessionbase login

# Provide token directly
sessionbase login --token YOUR_TOKEN_HERE
```

**Options:**

* `--token <token>` - Authentication token available at [https://www.sessionbase.ai/settings](https://www.sessionbase.ai/settings).

### `sessionbase whoami`

Display current authentication status and user information.

```bash
sessionbase whoami
```

### `sessionbase logout`

Log out and remove stored authentication token.

```bash
sessionbase logout
```

## Platform-Specific Behavior

SessionBase can automatically push your current chat session for Claude Code, Amazon Q Chat, and Codex CLI. For the Gemini CLI, you must first run the `/chat save <TAG>` command first, then SessionBase can detect and push from there. The table below summarizes some of the platform specific behavior.

| 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 (unless `/save <PATH>` used) | Can detect and push current session automatically      |
| **OpenAI Codex CLI** | Stores all session files automatically                                     | Can push current session or list/choose from directory |

## Examples

### Push Current Session

```bash
# Push most recent Claude Code session
sessionbase push --claude --title "Feature Implementation" --tags "feature,react"

# Push most recent Gemini CLI session (after saving with /chat save)
sessionbase push --gemini --private

# Push most recent Q Chat session
sessionbase push --qchat --summary "Debugging API integration issues"

# Push most recent Codex CLI session
sessionbase push --codex --title "Machine Learning Implementation" --tags "ml,python"
```

### Browse Sessions

```bash
# See all local sessions
sessionbase ls --global

# Find Claude Code sessions in a specific project
sessionbase ls --claude --path ~/projects/my-app

# List all Gemini CLI sessions in your current directory
sessionbase ls --gemini

# Find Codex CLI sessions across all projects
sessionbase ls --codex --global
```

### Manual File Push

```bash
# Push a specific session file
sessionbase push ./exported-session.json --title "Manual Export"

# Push with full metadata
sessionbase push ./debug-session.jsonl \
  --title "Database Migration Debug" \
  --tags "database,migration,debugging" \
  --summary "Troubleshooting foreign key constraints" \
  --private
```

### Collaborative Workflows

**Sharing Sessions:**

```bash
# Team member A shares a debugging session
cd ~/my-project
sessionbase push --claude --title "API Authentication Bug" --tags "debugging,auth,api"
# Returns: Session shared: https://sessionbase.ai/sessions/abc123

# Team member B can view the session at the provided URL
# Continue debugging in a new session, then share progress
sessionbase push --claude --title "API Auth Bug - Investigation Update" --tags "debugging,auth,progress"
```

## Tips

### Organizing Pushes

* Use meaningful titles and tags for better organization
* Summaries help when browsing sessions later

### Workflow Integration

* Use the MCP server for seamless pushes during AI conversations
* Regular pushes create a searchable history of your AI-assisted development
* Consider linking sessions in team documentation or in pull requests


# Introduction
Source: https://docs.sessionbase.ai/index

SessionBase - Share AI chat sessions with developers

## What is SessionBase?

SessionBase is a developer tool for sharing AI chat sessions. It allows you to capture, store, and share your AI conversations with team members, creating a knowledge base of your development processes.

## Getting Started

<CardGroup cols={2}>
  <Card title="MCP Server" icon="server" href="/mcp-server/installation">
    Push sessions directly from Claude Code, Gemini CLI, Q Chat, or Codex CLI using natural language.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/installation">
    Install and use the SessionBase CLI to manage your AI sessions.
  </Card>
</CardGroup>


# MCP Server
Source: https://docs.sessionbase.ai/mcp-server/installation

The SessionBase MCP server enables you to push and manage AI agent sessions directly from Claude Code, Gemini CLI, and Amazon Q Chat without breaking your workflow.

## Quick Setup

### 1. Install

```bash
npm install -g @sessionbase/cli
```

This single package provides both the CLI and MCP server.

### 2. Authenticate

```bash
sessionbase login
```

Complete the OAuth flow in your browser with Github or Google. Authentication is shared between the CLI and MCP server automatically.

### 3. Configure Your AI Chat App

SessionBase currently supports [Claude Code](https://www.anthropic.com/claude-code), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Amazon Q Chat](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html), and [OpenAI Codex CLI](https://developers.openai.com/codex/cli).

#### Claude Code

Use the built-in MCP management command:

```bash
claude mcp add sessionbase sessionbase-mcp --scope user
```

#### Gemini CLI

Add to your Gemini MCP configuration file at `~/.gemini/settings.json`:

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

#### Amazon Q Chat

Add to your Q Chat MCP configuration at `~/.aws/amazonq/mcp.json`:

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

#### OpenAI Codex CLI

Add to your Codex configuration at `~/.codex/config.toml`:

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

### 4. Start Using

Once configured, you can use natural language in your AI chat:

* "Push this to SessionBase"
* "List my recent Claude code sessions"
* "Push this session as private with the tags 'API debugging'"

#### Custom Slash Commands

##### Claude Code

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

Now from claude you can simply run `/upload` and Claude will automatically generate metadata and push to SessionBase for you.
You can also choose a different alias for your custom slash command by renaming `upload.md` to another file. For more details on custom slash commands, see the [Anthropic docs](https://docs.anthropic.com/en/docs/claude-code/slash-commands#personal-commands).

##### Gemini CLI

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

Then add this content to `~/.gemini/commands/upload.toml`:

```toml
# ~/.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. For more details on Gemini custom slash commands, see the [Google Cloud docs](https://cloud.google.com/blog/topics/developers-practitioners/gemini-cli-custom-slash-commands).

Amazon Q Chat and OpenAI Codex CLI do not currently support custom slash commands. You can still use natural language to push sessions (e.g., "Push this to SessionBase"), or use the CLI directly.

## Available Commands

The MCP server exposes these tools through natural language:

* **Push Session**: Share your current or recent AI coding sessions
* **List Sessions**: Browse your local session history
* **Check Status**: Verify authentication and connection

## Troubleshooting

### "No such file or directory" Error

If you see this error, ensure the package is installed globally:

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

### Authentication Issues

Verify you're logged in:

```bash
sessionbase whoami
```

If not authenticated, run `sessionbase login` again.

### Platform-Specific Session Detection

SessionBase can automatically push your current chat session for Claude Code and Amazon Q Chat. For the Gemini CLI, you must run the `/chat save <TAG>` command first, then SessionBase can push from there. The table below summarizes some of the platform specific behavior.

| 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 (unless `/save <PATH>` used) | Can detect and push current session automatically      |
| **OpenAI Codex CLI** | Stores all session files automatically                                     | Can push current session or list/choose from directory |