dropbox-paper-cli 0.2.0

CLI tool wrapping all Dropbox Paper SDK operations with local metadata caching and keyword search

dropbox-paper-cli

A Python CLI tool for managing Dropbox Paper documents from the terminal — browse files, create and edit Paper docs, read as Markdown, and search across your entire workspace with a local metadata cache.

Features

• OAuth2 Authentication — PKCE flow with automatic token refresh
• File Operations — list, create, read, write, move, copy, delete, create folders, get sharing links
• Paper Doc Creation — create new Paper documents from Markdown, HTML, or plain text
• Paper Doc Updates — overwrite, append, prepend, or revision-safe update existing Paper documents
• Paper Doc Export — read Paper documents as Markdown directly in your terminal
• Local Cache & Search — sync your full Dropbox directory tree to a local SQLite database for instant keyword search (FTS5 + CJK fallback)
• Parallel Sync — 20-concurrent-worker pipeline for large workspaces
• Team Account Support — automatic namespace detection for Dropbox Business accounts
• JSON Output — --json flag on all commands for scripting

Installation

Requires Python 3.12+.

# Run directly with uvx (no install needed)
uvx dropbox-paper-cli --help

# Or install with uv (recommended)
uv tool install dropbox-paper-cli

# Or with pip
pip install dropbox-paper-cli

Setup

1. Create a Dropbox App

Go to the Dropbox App Console and create a new app:

• Choose Scoped access
• Choose Full Dropbox access type
• Give it any name you like

Under the Permissions tab, enable:

• files.metadata.read
• files.content.read
• files.content.write
• sharing.read
• sharing.write

2. Configure Credentials

Use the CLI to set your app credentials:

paper config set --app-key YOUR_APP_KEY
paper config set --app-secret YOUR_APP_SECRET  # optional

Or create the config file manually at ~/.config/dropbox-paper-cli/config.json:

{
    "app_key": "YOUR_APP_KEY",
    "app_secret": "YOUR_APP_SECRET"
}

app_secret is optional — if omitted, the PKCE flow is used (no secret needed, recommended for personal use).

Environment variables DROPBOX_APP_KEY / DROPBOX_APP_SECRET take priority over the config file.

3. Authenticate

paper auth login

Follow the browser prompt to authorize the app.

Quick Start

# 1. Authenticate with Dropbox
paper auth login

# 2. Create a Paper document
echo "# My First Doc" | paper files create /My First Doc.paper

# 3. Read it back as Markdown
paper files read "/My First Doc.paper"

# 4. Sync metadata cache for search
paper cache sync

# 5. Search for documents
paper cache search "meeting notes"

Commands

Authentication

paper auth login     # OAuth2 login flow
paper auth logout    # Clear stored credentials
paper auth status    # Check authentication state

Configuration

paper config set --app-key KEY       # Set Dropbox app key
paper config set --app-secret SECRET # Set Dropbox app secret
paper config show                    # Show current config
paper config path                    # Show config file path

File Operations

paper files list [PATH]              # List files and folders
paper files metadata PATH            # Get detailed metadata
paper files read PATH                # Read Paper doc as Markdown
paper files create PATH              # Create a new Paper document
paper files write PATH               # Update a Paper document
paper files link PATH                # Get/create sharing link
paper files create-folder PATH       # Create a new folder
paper files move SRC DST             # Move file or folder
paper files copy SRC DST             # Copy file or folder
paper files delete PATH              # Delete file or folder

Creating Paper Documents

# From stdin (pipe-friendly)
echo "# Meeting Notes" | paper files create /notes/Meeting.paper

# From a local file
paper files create /notes/Meeting.paper --file notes.md

# HTML format
paper files create /doc.paper --format html --file page.html

Updating Paper Documents

# Overwrite entire content (default)
echo "# Updated" | paper files write /doc.paper

# Append content to end
echo "## Appendix" | paper files write /doc.paper --policy append

# Prepend content to beginning
echo "## Header" | paper files write /doc.paper --policy prepend

# Safe update with revision check (fails if doc changed since given revision)
paper files write /doc.paper --policy update --revision 5 --file new.md

# From a local file with format
paper files write /doc.paper --file content.md --format markdown

Cache & Search

paper cache sync                     # Incremental sync (default)
paper cache sync --full              # Full resync
paper cache sync --path "/subfolder" # Sync specific subtree
paper cache sync --concurrency 10    # Custom worker count

paper cache search QUERY             # Search by keyword
paper cache search QUERY --type paper   # Filter: paper docs only
paper cache search QUERY --type folder  # Filter: folders only
paper cache search QUERY --type file    # Filter: regular files only
paper cache search QUERY --limit 20     # Limit results

Sharing

paper sharing info FOLDER_ID_OR_URL  # Get sharing info for a shared folder

Global Options

paper --json ...      # JSON output for scripting
paper --verbose ...   # Diagnostic output to stderr
paper --version       # Show version

Data Storage

Follows the XDG Base Directory Specification:

Purpose	Default Path	Override
Config (config.json, tokens)	~/.config/dropbox-paper-cli/	PAPER_CLI_CONFIG_DIR
Data (cache DB)	~/.local/share/dropbox-paper-cli/	PAPER_CLI_DATA_DIR

Development

# Clone and install dev dependencies
git clone https://github.com/Koswu/dropbox-paper-cli.git
cd dropbox-paper-cli
uv sync --group dev

# Run tests
uv run pytest

# Lint & format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Type check
uv run ty check

# Pre-commit hooks (ruff + ty)
uv run pre-commit install
uv run pre-commit run --all-files

License

MIT