CandleKeep CLI (ck)

Command-line interface for managing your CandleKeep document library.

Installation

Using cargo-binstall (Recommended)

The fastest way to install - downloads a pre-built binary:

cargo binstall candlekeep-cli

Using cargo install

Compiles from source (requires Rust toolchain):

cargo install candlekeep-cli

Download Binary

Download the latest release for your platform from GitHub Releases.

After downloading, extract and move to your PATH:

# macOS/Linux
tar -xzf ck-*.tar.gz
chmod +x ck
sudo mv ck /usr/local/bin/

# Windows - extract zip and add to PATH

Quick Start

# Login to your CandleKeep account
ck auth login

# List your library
ck items list

# Read a book
ck items read <id> --pages "1-10"

# Upload a PDF
ck items add ./book.pdf

Usage

Authentication

# Login via browser (opens auth flow)
ck auth login

# Show current user info
ck auth whoami

# Logout
ck auth logout

Managing Items

# List all items
ck items list

# Read content from items
ck items read <id>
ck items read <id1>,<id2>              # Multiple items
ck items read <id> --pages "1-5"       # Specific pages
ck items read <id> --pages "1,3,5-10"  # Mixed ranges

# Show table of contents
ck items toc <id>
ck items toc <id1>,<id2>

# Upload a PDF
ck items add ./document.pdf

# Remove items
ck items remove <id>
ck items remove <id1>,<id2> --yes      # Skip confirmation

Output Format

Add --json flag to any command for JSON output:

ck items list --json
ck auth whoami --json

Configuration

Configuration is stored at ~/.candlekeep/config.toml:

[auth]
api_key = "ck_xxxxxxxxxx"

[api]
url = "https://www.getcandlekeep.com"

Development

# Clone the repository
git clone https://github.com/CandleKeepAgents/candlekeep-cloud.git
cd candlekeep-cloud/apps/cli

# Build
cargo build

# Run
cargo run -- auth whoami

# Test
cargo test

License

MIT License - see LICENSE for details.