Diskd CLI

diskd CLI

diskd is a Rust command-line client for diskd platform and Drive APIs. It gives humans, shell scripts, and coding agents a Unix-style interface for listing, reading, searching, uploading, syncing, and querying Drive files through the public apis-service gateway. Output is human text by default and machine-readable JSON with --json.

Command Shape

diskd [GLOBAL FLAGS] <command> [ARGS] [FLAGS]

Global flags MUST be placed before the subcommand. diskd --json ls docs works; diskd ls docs --json does not.

Install

# Latest release (detects platform, verifies .sha256, installs `diskd`)
curl -fsSL https://raw.githubusercontent.com/diskd-ai/diskd-cli/main/install.sh | sh

# Pin a version
curl -fsSL https://raw.githubusercontent.com/diskd-ai/diskd-cli/main/install.sh | DISKD_VERSION=v0.2.0 sh

# Custom directory
curl -fsSL https://raw.githubusercontent.com/diskd-ai/diskd-cli/main/install.sh | DISKD_INSTALL_DIR="$HOME/bin" sh

Update an installed binary with diskd update (--force to reinstall the latest even when versions match). Human-facing commands print a yellow stderr update notice when a newer release exists; the check is skipped for --json, --quiet, and diskd mcp serve, and disabled by DISKD_NO_UPDATE_CHECK=1.

Quick Start: auth -> context -> files

# 1. Authenticate (browser login stores only the bearer token under $DISKD_HOME/credentials)
diskd login                                       # use --dev for https://app.upgraide.dev/oauth-apps
diskd login --token "$APIS_ACCESS_TOKEN"          # non-interactive token login

# 2. Verify identity (decodes workspace/subject from the token; never prints it)
diskd --json whoami

# 3. Pick a project as the current path context
diskd --json project list                         # list accessible projects
diskd set-context 01PROJECTID                     # select project path/session scope
diskd get-context                                 # show current context
diskd set-context --root                           # clear project, use workspace root

# 4. Work with files under that context
diskd mkdir docs
diskd upload ./report.pdf --dest docs --force
diskd ls docs
diskd --json download docs/report.pdf ./report.pdf
diskd --json grep "payment terms" docs
diskd --json vsearch "contract renewal clauses" docs/report.pdf --top 5

# 5. Read sessions in the selected project
diskd --json session list
diskd --json session read 01SESSIONID --limit 20
diskd --json session messages 01SESSIONID --limit 20

Command Surface at a Glance

Full flag-by-flag detail and the exact Drive API method each command calls are in references/commands.md.

Path Rules

Paths are resolved relative to the current context. The CLI rejects . and .. segments before any network call.

# No project context (workspace root)
docs/a.txt   -> /docs/a.txt

# Project 01PROJECT selected
docs/a.txt   -> /Projects/01PROJECT/docs/a.txt

The selected project is local CLI context only; it is never sent as a public Drive API field. See references/auth-and-config.md.

Key Behaviors to Know

• --json before the command for scripting; pipe into jq: diskd --json set-context --list | jq -r '.[].name'.
• vsearch reliability: a specific file path is more reliable than a directory path, because the backend may not expand directory inodes for vector search. If a directory vsearch fails with a "directory without file id" style error, retry against a file or use grep.
• grep flags --ignore-case / --files-with-matches are parsed but rejected -- the current Drive grep contract has no matching fields. Do not rely on them.
• cat writes bytes to stdout, so redirection and pipes work as expected.
• Read sessions by domain ID with session list, session read, and session messages; never construct .sessions paths or pass inodes.
• Session and project mutations are state-changing. Run save, append, remove, rollback, and delete only when authorized. Destructive delete commands require --yes.
• download is atomic and refuses to replace a local destination unless --force is explicitly supplied.
• biquery takes a plain-language question, not SQL. The Drive backend reads the spreadsheet schema and uses an LLM to generate and run the SQL, returning a result table, e.g. diskd --json biquery "total amount grouped by name" data/table.csv. Point it at indexed spreadsheet files (.csv, .tsv, .xls, .xlsx, .mailbox); a directory path is expanded to the spreadsheet files inside.
• database query is the generic SQL path. It calls drive/db/query. Use --db-type telegram/webarchive/session when needed to disambiguate typed DB names. database also exposes commit, rollback, metadata, drop, status, and inode resolution methods.
• telegram-db query is the SQL path. It calls drive/telegram/query against a named Telegram SQLite DB. Use --parameters '[...]' for positional SQL parameters. telegram-db insert requires a JSON array through --rows or --rows-file.
• upload preserves paths relative to each provided local directory and computes SHA-256 per file (start -> PUT bytes -> commit).

References

• Full command reference (every flag + Drive method): references/commands.md
• Auth, config, env vars, path context: references/auth-and-config.md
• MCP stdio server (config, tool names, JSON-RPC smoke tests): references/mcp.md
• End-to-end workflows (CSV/BI, CI, sync, agent integration, troubleshooting): references/workflows.md