dropbox-paper-cli 0.3.0

CLI tool for Dropbox Paper: async file operations, Paper doc management, local metadata cache with FTS5 search, and interactive TUI

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, search across your entire workspace with a local metadata cache, and interactively explore results in a TUI. Built on httpx for fully async HTTP communication.

Features

• OAuth2 Authentication — PKCE flow with automatic token refresh
• Async HTTP — built on httpx with concurrent API requests and token auto-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)
• Interactive TUI Search — Textual-powered interactive search with keyboard shortcuts to get links, open in browser, or preview documents
• Parallel Sync — 20-concurrent-worker pipeline for large workspaces (configurable)
• Team Account Support — automatic namespace detection for Dropbox Business accounts
• JSON Output — --json flag on all commands for scripting
• Verbose Logging — --verbose flag for diagnostic output on all commands

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

paper cache isearch                  # Interactive TUI search
paper cache isearch "initial query"  # Open TUI with pre-filled query

Interactive Search (TUI) Key Bindings:

Key	Action
Enter	Move focus to results table
F2	Get sharing link for selected item
F3	Open selected item in browser
F4	Preview Paper document content
Escape	Quit

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

Architecture

• HTTP Layer: httpx-based async client (lib/http_client.py) with automatic token refresh, retry logic, and Dropbox API v2 RPC/content endpoints
• Services: DropboxService (file/folder ops), SharingService, CacheService (sync), standalone search_cache() for FTS5 queries
• CLI: Typer-based commands with run_with_client() helper for consistent async execution
• TUI: Textual-powered interactive search app with background workers for network operations
• Cache: SQLite with FTS5 full-text search, LIKE fallback for CJK, WAL mode for concurrent reads

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