> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sessionbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
sessionbase whoami
```

### `sessionbase logout`

Log out and remove stored authentication token.

```bash theme={null}
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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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