From 673fda900200f4235b77930b4ded9ee8ea7e2447 Mon Sep 17 00:00:00 2001 From: Ehsaan Date: Thu, 15 Jan 2026 16:12:50 -0800 Subject: [PATCH 1/2] repo: add README --- README.md | 275 +++++++++++++++++++++++++++++++++++++++++++++++++++++ install.sh | 173 ++++++++++++++++++++++++++++++--- 2 files changed, 437 insertions(+), 11 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3f3faef --- /dev/null +++ b/README.md @@ -0,0 +1,275 @@ +# 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) + +```bash +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: + +```bash +curl -fsSL https://livedocs.com/install.sh | bash -s -- --setup-path +``` + +### Requirements + +- macOS (arm64/x86_64) or Linux (amd64/arm64) +- [uv](https://docs.astral.sh/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: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +### Verify Installation + +```bash +livedocs --version +livedocs --help +``` + +## Quick Start + +1. **Pair with your workspace** + + ```bash + livedocs setup + ``` + + This opens your browser to authenticate. Once approved, your workspace token is stored securely in your system keychain. + +2. **Launch a notebook** + + ```bash + 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: + + ```bash + livedocs stop + ``` + +## Commands + +### `livedocs setup` + +Pair the CLI with your Livedocs workspace using device-code authentication. + +```bash +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 launch` + +Start a local runtime session for a notebook. + +```bash +livedocs launch # Interactive notebook picker +livedocs launch --notebook # Launch specific notebook by ID +livedocs launch --new # Create and launch a new notebook +livedocs launch --new --import # 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. + +```bash +livedocs stop # Stop the most recent session +livedocs stop --id # Stop a specific session +livedocs stop --all # Stop all sessions +``` + +### `livedocs status` + +Show installed bundle version and session history. + +```bash +livedocs status +livedocs status --verbose # Include additional debug info +``` + +### `livedocs logs` + +Tail logs from runtime processes. + +```bash +livedocs logs # Tail all logs +livedocs logs --session # 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. + +```bash +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. + +```bash +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. + +```bash +livedocs whoami +``` + +### `livedocs logout` + +Remove stored workspace tokens. + +```bash +livedocs logout +``` + +## Configuration + +Configuration is stored in `~/.livedocs/config.toml`: + +```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: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +### Session fails to start + +Check the logs: + +```bash +livedocs logs --session +``` + +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: + +```bash +livedocs logout +livedocs setup +``` + +## Uninstall + +Remove the CLI and all data: + +```bash +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) +- 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://docs.livedocs.com +- Issues: support@livedocs.com diff --git a/install.sh b/install.sh index f45d037..665003a 100755 --- a/install.sh +++ b/install.sh @@ -23,6 +23,8 @@ BUCKET_OVERRIDE="${LIVEDOCS_BUCKET-}" FORCE=0 QUIET=0 NO_SYMLINK=0 +SETUP_PATH=0 +SKIP_PATH=0 bold="" dim="" @@ -62,7 +64,8 @@ Livedocs Anywhere installer Usage: curl -fsSL | bash - ./install.sh [--channel ] [--version ] [--manifest-url ] [--install-dir ] [--force] [--quiet] + curl -fsSL | bash -s -- --setup-path + ./install.sh [OPTIONS] Options: --channel Release channel to install (default: stable) @@ -71,6 +74,8 @@ Options: --install-dir Installation root (default: ~/.livedocs) --bucket Override storage bucket (defaults to channel mapping) --no-symlink Skip updating ~/.livedocs/bin symlink (manual control) + --setup-path Automatically add livedocs to PATH (modifies shell profile) + --skip-path Skip PATH setup entirely (no prompt) --force Reinstall even if version already present --quiet Minimize output (errors still shown) --help Show this help message @@ -80,7 +85,8 @@ Environment overrides: LIVEDOCS_BUCKET, LIVEDOCS_PROD_BUCKET, LIVEDOCS_STAGING_BUCKET Examples: - curl -fsSL https://downloads.livedocs.com/cli/install.sh | bash + curl -fsSL https://livedocs.com/install.sh | bash + curl -fsSL https://livedocs.com/install.sh | bash -s -- --setup-path LIVEDOCS_VERSION=0.2.1 ./install.sh --force EOF @@ -120,6 +126,14 @@ while [[ $# -gt 0 ]]; do NO_SYMLINK=1 shift ;; + --setup-path) + SETUP_PATH=1 + shift + ;; + --skip-path) + SKIP_PATH=1 + shift + ;; --help|-h) usage exit 0 @@ -438,24 +452,160 @@ ensure_dir() { fi } -maybe_warn_path() { +PATH_MARKER="# Added by Livedocs (livedocs.com)" + +detect_shell_rc() { + local shell_name rc_file + shell_name=$(basename "${SHELL:-/bin/bash}") + + case "$shell_name" in + zsh) + rc_file="$HOME/.zshrc" + ;; + bash) + # Prefer .bashrc for interactive shells, fall back to .bash_profile + if [[ -f "$HOME/.bashrc" ]]; then + rc_file="$HOME/.bashrc" + elif [[ -f "$HOME/.bash_profile" ]]; then + rc_file="$HOME/.bash_profile" + else + rc_file="$HOME/.bashrc" + fi + ;; + fish) + rc_file="$HOME/.config/fish/config.fish" + ;; + *) + # Default to .profile for POSIX shells + rc_file="$HOME/.profile" + ;; + esac + + echo "$rc_file" +} + +path_already_configured() { local bin_dir=$1 + local rc_file=$2 + + # Check if already in current PATH case ":$PATH:" in *":${bin_dir}:"*) + return 0 ;; - *) - cat </dev/null; then + return 0 + fi + if grep -qF "${bin_dir}" "$rc_file" 2>/dev/null; then + return 0 + fi + fi - export PATH="${bin_dir}:\$PATH" + return 1 +} + +add_path_to_rc() { + local bin_dir=$1 + local rc_file=$2 + local shell_name + shell_name=$(basename "${SHELL:-/bin/bash}") -Then restart your shell or run 'source ' to pick up the change. + # Ensure parent directory exists (for fish) + mkdir -p "$(dirname "$rc_file")" + + # Append PATH export with marker + if [[ "$shell_name" == "fish" ]]; then + cat >> "$rc_file" <> "$rc_file" <&2 + local answer + read -r answer Date: Thu, 15 Jan 2026 16:20:34 -0800 Subject: [PATCH 2/2] repo: update documentation link in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3f3faef..a12bb94 100644 --- a/README.md +++ b/README.md @@ -271,5 +271,5 @@ Remove the PATH entry from your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) if ## Support -- Documentation: https://docs.livedocs.com +- Documentation: https://livedocs.com/docs - Issues: support@livedocs.com