Commands Reference

This page documents all available commands in the Livedocs CLI.

Authentication

`livedocs setup`

Pair the CLI with your Livedocs workspace.

livedocs setup

Options:

Flag	Description
`--api-token TOKEN`	Use a pre-generated API token instead of browser auth
`--no-browser`	Print the auth URL instead of opening it automatically

Examples:

# Interactive browser-based authentication
livedocs setup

# Use an API token (for headless servers)
livedocs setup --api-token ldsk_abc123...

# Get the auth URL without opening a browser
livedocs setup --no-browser

`livedocs whoami`

Display current authentication and workspace information.

livedocs whoami

Shows your workspace ID, workspace name, and account email.

`livedocs logout`

Remove stored workspace tokens from your system keychain.

livedocs logout

Sessions

`livedocs launch`

Start a local runtime session for a notebook.

livedocs launch

Options:

Flag	Description
`--notebook ID`	Launch a specific notebook by ID
`--new`	Create a new notebook before launching
`--import PATH`	Import a Jupyter `.ipynb` file (requires `--new`)
`--attach`	Keep the terminal attached to stream logs

Examples:

# Interactive notebook picker
livedocs launch

# Launch a specific notebook
livedocs launch --notebook abc123

# Create and launch a new notebook
livedocs launch --new

# Import an existing Jupyter notebook
livedocs launch --new --import analysis.ipynb

# Stay attached to see logs
livedocs launch --attach

By default, sessions run detached (in the background). Use --attach to see logs inline and stop with Ctrl+C.

`livedocs stop`

Stop a running runtime session.

livedocs stop

Options:

Flag	Description
`--id ID`	Stop a specific session by ID
`--all`	Stop all running sessions

Examples:

# Stop the most recent session
livedocs stop

# Stop a specific session
livedocs stop --id 01234567-89ab-cdef-...

# Stop all sessions
livedocs stop --all

`livedocs status`

Show installed bundle version and session history.

livedocs status

Options:

Flag	Description
`--verbose`	Show additional troubleshooting details

Displays:

Current bundle version
Python runtime version
Session history table (status, started time, notebook ID, session ID, endpoint, PIDs)

`livedocs logs`

Tail logs from runtime processes.

livedocs logs

Options:

Flag	Description
`--session ID`	Show logs for a specific session
`--target TARGET`	Filter by process: `middleman`, `jedi`, or `all`

Examples:

# Tail all logs from the current session
livedocs logs

# Logs for a specific session
livedocs logs --session 01234567-89ab-cdef-...

# Only Middleman (runtime) logs
livedocs logs --target middleman

# Only Jedi (AI) logs
livedocs logs --target jedi

Maintenance

`livedocs update`

Update the CLI to the latest available bundle.

livedocs update

Options:

Flag	Description
`--check-only`	Check for updates without installing
`--force`	Reinstall the current version
`--channel NAME`	Switch release channel (stable, staging)
`--bundle-version VERSION`	Install a specific version

Examples:

# Update to the latest version
livedocs update

# Check if an update is available
livedocs update --check-only

# Reinstall the current version (useful for fixing corrupted installs)
livedocs update --force

# Switch to the staging channel
livedocs update --channel staging

`livedocs gc`

Garbage collect old sessions and runtime artifacts.

livedocs gc

Options:

Flag	Description
`--all`	Remove all stopped sessions (not just old ones)
`--dry-run`	Show what would be removed without deleting

Examples:

# Clean up sessions older than 7 days
livedocs gc

# Remove all stopped sessions
livedocs gc --all

# Preview what would be removed
livedocs gc --dry-run

Configuration

Environment Variables

Variable	Description
`LIVEDOCS_HOME`	Override the root directory (default: `~/.livedocs`)
`LIVEDOCS_API_BASE_URL`	Override the API endpoint
`LIVEDOCS_WEB_BASE_URL`	Override the web app URL

Config File

Configuration is stored in ~/.livedocs/config.toml:

channel = "stable"
api_base_url = "https://api.livedocs.com"
web_base_url = "https://livedocs.com"

Directory Structure

The CLI stores all data under ~/.livedocs/:

~/.livedocs/
  bin/              # CLI binary symlink
  bundles/          # Downloaded CLI bundles by version
  current/          # Symlink to active bundle
  runtime/          # Python environments and session workspaces
  sessions/         # Session metadata (JSON files)
  logs/             # Log files organized by session
  user_files/       # Persistent working directory for notebooks
  config.toml       # CLI configuration