Livedocs CLI

Run Livedocs notebooks locally on your machine while using the hosted web interface.

Livedocs CLI lets you execute Python notebooks with full access to local files, databases, and compute resources. The runtime (Middleman + Jedi) runs on your machine; the editing experience stays in the browser at livedocs.com.

Installation

Quick Install (recommended)

curl -fsSL https://livedocs.com/install.sh | bash

The installer will prompt to add ~/.livedocs/bin to your PATH. To skip the prompt and auto-configure:

curl -fsSL https://livedocs.com/install.sh | bash -s -- --setup-path

Requirements

• macOS (arm64/x86_64) or Linux (amd64/arm64)
• uv - Python package manager (the installer will check for this)
• Python 3.12 (installed automatically via uv)

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify Installation

livedocs --version
livedocs --help

Quick Start

1. Pair with your workspace

   livedocs setup

   This opens your browser to authenticate. Once approved, your workspace token is stored securely in your system keychain.

2. Launch a notebook

   livedocs launch

   Select from your recent notebooks or create a new one. The CLI starts the runtime and opens the editor in your browser.

3. Stop the session

   Press Ctrl+C in the terminal, or:

   livedocs stop

Commands

livedocs setup

Pair the CLI with your Livedocs workspace using device-code authentication.

livedocs setup                    # Interactive browser-based auth
livedocs setup --api-token TOKEN  # Use a pre-generated API token
livedocs setup --no-browser       # Print the auth URL instead of opening it
livedocs setup --token-store file # Store token in local file (headless/SSH)

livedocs launch

Start a local runtime session for a notebook.

livedocs launch                        # Interactive notebook picker
livedocs launch --notebook <ID>        # Launch specific notebook by ID
livedocs launch --new                  # Create and launch a new notebook
livedocs launch --new --import <file>  # Import a Jupyter .ipynb file
livedocs launch --attach               # Keep terminal attached to stream logs

By default, sessions run detached. Use --attach to see logs inline.

livedocs stop

Stop a running session.

livedocs stop              # Stop the most recent session
livedocs stop --id <ID>    # Stop a specific session
livedocs stop --all        # Stop all sessions

livedocs status

Show installed bundle version and session history.

livedocs status
livedocs status --verbose  # Include additional debug info

livedocs logs

Tail logs from runtime processes.

livedocs logs                      # Tail all logs
livedocs logs --session <ID>       # Logs for a specific session
livedocs logs --target middleman   # Only Middleman logs
livedocs logs --target jedi        # Only Jedi (AI) logs

livedocs update

Update to the latest CLI bundle.

livedocs update              # Update to latest
livedocs update --check-only # Check without installing
livedocs update --force      # Reinstall current version
livedocs update --channel staging  # Switch release channel

livedocs gc

Clean up old sessions and runtime artifacts.

livedocs gc                # Remove stopped sessions older than 7 days
livedocs gc --all          # Remove all stopped sessions
livedocs gc --dry-run      # Show what would be removed

livedocs whoami

Display current authentication and workspace info.

livedocs whoami

livedocs logout

Remove stored workspace tokens.

livedocs logout

Configuration

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

channel = "stable"                          # Release channel (stable, staging, dev)
api_base_url = "https://api.livedocs.com"   # Core API endpoint
web_base_url = "https://livedocs.com"       # Web app URL

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
LIVEDOCS_CHANNEL	Override release channel for install script
LIVEDOCS_VERSION	Pin to a specific CLI version

Directory Structure

~/.livedocs/
  bin/                  # CLI binary symlink
  bundles/              # Downloaded CLI bundles by version
    1.2.1/
      bin/
      middleman/
      wheels/
      manifest.json
  current -> bundles/1.2.1  # Active bundle symlink
  runtime/              # Python environments and session workspaces
    1.2.1/
      python/           # uv-managed Python environment
      jedi/             # Jedi (AI service) environment
      sessions/         # Per-session runtime directories
  sessions/             # Session metadata (JSON)
  logs/                 # Log files by session
  user_files/           # Persistent working directory for notebooks
  config.toml           # CLI configuration

How It Works

When you run livedocs launch:

1. The CLI authenticates with Livedocs Core using your workspace token
2. Core allocates a runtime session and returns connection credentials
3. The CLI bootstraps a Python environment (if needed) using uv
4. Middleman (the notebook runtime) and Jedi (AI assistant) start as supervised processes
5. Your browser opens the Livedocs editor, connected to your local runtime
6. Code executes locally with full access to your machine's resources

The web interface handles editing, collaboration features, and notebook persistence. The local runtime handles code execution, file I/O, and AI operations.

Troubleshooting

"command not found: livedocs"

Your PATH doesn't include ~/.livedocs/bin. Either:

• Run source ~/.zshrc (or your shell's rc file)
• Open a new terminal
• Re-run the installer with --setup-path

"uv is required"

Install uv first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Session fails to start

Check the logs:

livedocs logs --session <ID>

Common issues:

• Port conflict: another process is using port 8000
• Missing dependencies: run livedocs update --force to reinstall
• Stale session: run livedocs gc to clean up

Authentication errors

Re-run setup to refresh your workspace token:

livedocs logout
livedocs setup

Uninstall

Remove the CLI and all data:

rm -rf ~/.livedocs

Remove the PATH entry from your shell profile (~/.zshrc, ~/.bashrc, etc.) if you used --setup-path.

Security

• Workspace tokens are stored in your system's secure credential storage (macOS Keychain, Linux Secret Service). If secure storage is unavailable, tokens fall back to ~/.livedocs/tokens.json with 0600 permissions.
• Session tokens are ephemeral and stored with restricted permissions (0600)
• All communication with Livedocs Core uses HTTPS
• Local runtime binds to localhost by default

Support

• Documentation: https://livedocs.com/docs
• Issues: support@livedocs.com