CLI Reference

Installation

npm install -g golemdrive-cli

Requires Node.js 18+. Config stored at ~/.golemdrive/config.json, auth at ~/.golemdrive/auth.json (0600 permissions).

Global Options

Available on all commands:

Flag	Description
--json	Output as JSON
--table	Output as table
--no-color	Disable colored output
-v, --verbose	Verbose logging
-q, --quiet	Suppress non-essential output
--api-url <url>	Override API base URL
-h, --help	Show help
-V, --version	Show version

Authentication

Interactive Login

golemdrive login

Opens browser for OIDC authentication. Config auto-discovered from API URL and cached 24 hours.

Non-Interactive (CI/CD)

export GD_USERNAME="you@example.com"
export GD_PASSWORD="your-password"
golemdrive upload ./dist/

Token-Based

golemdrive login --token eyJhbGci...

Logout

golemdrive logout          # Clear local tokens
golemdrive logout --revoke # Also revoke on server

---

File Management

ls

List files in a folder.

golemdrive ls [folder-uuid]

Option	Type	Default	Description
--sort <field>	string	name	Sort field (name, size, created, modified)
--page <n>	number	1	Page number
--per-page <n>	number	20	Items per page
--type <filter>	string		Filter by type: images, videos, audio, documents, compressed
--recent	boolean	false	Show recently modified files
--days <n>	number	7	Number of days for --recent

golemdrive ls
golemdrive ls abc123-def456 --sort size --per-page 50
golemdrive ls --type images --recent --days 14

upload

Upload a file or directory. Files are encrypted locally with AES-256-GCM before upload.

golemdrive upload <file>

Option	Type	Default	Description
--folder <uuid>	string	root	Target folder UUID
--favorite	boolean	false	Mark as favorite after upload
--shareable	boolean	false	Enable sharing on the uploaded file
--public	boolean	false	Make publicly accessible
--volume <name>	string		Target storage volume
--chunk-size <bytes>	number	5242880	Chunk size in bytes (default 5 MB)
--concurrency <n>	number	4	Number of parallel upload streams
--passphrase <phrase>	string		Encryption passphrase (overrides keypair)
--keep-temp	boolean	false	Keep temporary encrypted chunks after upload

Environment variable: GD_PASSPHRASE — sets the encryption passphrase without exposing it in shell history.

golemdrive upload report.pdf
golemdrive upload ./photos/ --folder abc123 --concurrency 8
golemdrive upload sensitive.docx --passphrase "correct horse battery staple"
GD_PASSPHRASE="secret" golemdrive upload vault.tar.gz

download

Download and decrypt one or more files.

golemdrive download <file-uuid...>

Option	Type	Default	Description
-o, --output <path>	string		Output file path (single file only)
--output-dir <dir>	string	.	Output directory for multiple files
--passphrase <phrase>	string		Decryption passphrase
--skip-verify	boolean	false	Skip integrity verification after download
--strict	boolean	false	Fail on any integrity mismatch
--keep-temp	boolean	false	Keep encrypted temp files
--concurrency <n>	number	4	Parallel download streams
--bulk	boolean	false	Bulk mode, accept UUIDs from stdin

golemdrive download abc123
golemdrive download abc123 def456 --output-dir ./downloads/
golemdrive download abc123 -o report.pdf --strict
echo -e "uuid1\nuuid2" | golemdrive download --bulk --output-dir ./batch/

mv

Move files or folders to a target folder. The last argument is the destination folder UUID.

golemdrive mv <uuids...>

Option	Type	Default	Description
--folder	boolean	false	Treat UUIDs as folder UUIDs
--bulk	boolean	false	Accept UUIDs from stdin

golemdrive mv abc123 def456 target-folder-uuid
golemdrive mv folder-uuid target-uuid --folder

cp

Copy a file to a target folder.

golemdrive cp <file-uuid> <target-folder-uuid>

golemdrive cp abc123 folder-uuid

rename

Rename a file or folder.

golemdrive rename <uuid> <new-name>

Option	Type	Default	Description
--folder	boolean	false	Treat UUID as a folder UUID

golemdrive rename abc123 "Q4 Report.pdf"
golemdrive rename folder-uuid "Archives" --folder

rm

Delete files or folders (moves to trash by default).

golemdrive rm <uuid...>

Option	Type	Default	Description
--permanent	boolean	false	Permanently delete, bypassing trash
--force	boolean	false	Skip confirmation prompt
--folder	boolean	false	Treat UUIDs as folder UUIDs
--bulk	boolean	false	Accept UUIDs from stdin

golemdrive rm abc123
golemdrive rm abc123 def456 --permanent --force
golemdrive rm folder-uuid --folder

restore

Restore files or folders from trash.

golemdrive restore <uuid...>

Option	Type	Default	Description
--folder	boolean	false	Treat UUIDs as folder UUIDs
--bulk	boolean	false	Accept UUIDs from stdin

golemdrive restore abc123
golemdrive restore abc123 def456 --folder

info

Display detailed metadata for a file or folder.

golemdrive info <uuid>

golemdrive info abc123
golemdrive info abc123 --json

favorite

Toggle favorite status on a file.

golemdrive favorite <uuid>

golemdrive favorite abc123

trash

List or manage trash contents.

golemdrive trash

Option	Type	Default	Description
--empty	boolean	false	Permanently empty all trash
--force	boolean	false	Skip confirmation when emptying
--show-location	boolean	false	Show original folder location

golemdrive trash
golemdrive trash --show-location
golemdrive trash --empty --force

favorites

List all favorited files.

golemdrive favorites

Option	Type	Default	Description
--page <n>	number	1	Page number
--page-size <n>	number	20	Items per page

golemdrive favorites --page 2 --page-size 50

recent

List recently modified files.

golemdrive recent

Option	Type	Default	Description
--days <n>	number	7	Lookback period in days
--page <n>	number	1	Page number
--page-size <n>	number	20	Items per page

golemdrive recent --days 30

update

Update file or folder metadata.

golemdrive update <uuid>

Option	Type	Default	Description
--name <name>	string		New name
--description <text>	string		New description
--public <value>	string		Visibility: yes, no, or inherit
--shareable	boolean		Enable sharing
--no-shareable	boolean		Disable sharing
--folder	boolean	false	Treat UUID as a folder UUID

golemdrive update abc123 --name "Final Report.pdf" --description "Q4 financials"
golemdrive update abc123 --public no --no-shareable

Type-Filtered Lists

Shortcut commands that filter by file type. All accept the same options.

golemdrive images
golemdrive videos
golemdrive audio
golemdrive documents
golemdrive compressed

Option	Type	Default	Description
--page <n>	number	1	Page number
--page-size <n>	number	20	Items per page

golemdrive images --page-size 100
golemdrive documents --page 3

---

Folders

mkdir

Create a new folder.

golemdrive mkdir <name>

Option	Type	Default	Description
--parent <uuid>	string	root	Parent folder UUID
-p, --nested	boolean	false	Create nested path (e.g., a/b/c)

golemdrive mkdir "Project Alpha"
golemdrive mkdir "2024/Q4/Reports" -p --parent abc123

tree

Display folder hierarchy as a tree.

golemdrive tree [folder-uuid]

Option	Type	Default	Description
--depth <n>	number	unlimited	Maximum depth to display
--json	boolean	false	Output as JSON

golemdrive tree
golemdrive tree abc123 --depth 3
golemdrive tree --json

---

Share Management

share create

Create a share link for a file.

golemdrive share create <file-uuid>

Option	Type	Default	Description
--password	boolean	false	Prompt for password interactively
--password-text <text>	string		Set password directly (use GD_SHARE_PASSWORD env var instead for security)
--expiry <value>	string	none	Expiry as ISO date (2024-12-31) or relative duration (7d, 24h, 30m)
--short	boolean	false	Generate a short URL
--download-limit <n>	number	unlimited	Maximum number of downloads
--notes <text>	string		Internal notes for the share

Environment variable: GD_SHARE_PASSWORD — sets the share password without shell history exposure.

golemdrive share create abc123
golemdrive share create abc123 --expiry 7d --download-limit 10
golemdrive share create abc123 --password --short
GD_SHARE_PASSWORD="secret" golemdrive share create abc123 --password-text "$GD_SHARE_PASSWORD"

share list

List all share links.

golemdrive share list

Option	Type	Default	Description
--filter-active	boolean	false	Show only active shares
--filter-expired	boolean	false	Show only expired shares
--page <n>	number	1	Page number
--per-page <n>	number	20	Items per page

golemdrive share list --filter-active
golemdrive share list --filter-expired --json

share delete

Delete a share link.

golemdrive share delete <id>

golemdrive share delete share-uuid

share info

Display details of a share link.

golemdrive share info <id>

golemdrive share info share-uuid
golemdrive share info share-uuid --json

share file-info

Display the file metadata associated with a share link.

golemdrive share file-info <id>

golemdrive share file-info share-uuid

share bulk

Create share links for multiple files or folders at once.

golemdrive share bulk <uuids...>

Option	Type	Default	Description
--type <value>	string	VR_FILE	Resource type: VR_FILE or VR_FOLDER
--view-only	boolean	false	Restrict to view-only access
--expires-in-days <n>	number		Expiry in days from now
--max-downloads <n>	number	unlimited	Maximum downloads per link

golemdrive share bulk abc123 def456 ghi789 --expires-in-days 30
golemdrive share bulk folder1 folder2 --type VR_FOLDER --view-only

share update

Update an existing share link.

golemdrive share update <uuid>

Option	Type	Default	Description
--name <name>	string		Display name
--download-limit <n>	number		Update download limit
--expiry <value>	string		New expiry (ISO date or relative)
--active <bool>	string		Enable or disable: true or false
--password	boolean	false	Prompt for new password
--password-text <text>	string		Set password directly

golemdrive share update share-uuid --download-limit 50 --expiry 14d
golemdrive share update share-uuid --active false

link

Generate a formatted share link for a file.

golemdrive link <file-uuid>

Option	Type	Default	Description
--format <type>	string	short	Output format: short, long, markdown, html

golemdrive link abc123
golemdrive link abc123 --format markdown

---

Account

account

Display account details including UUID, type, level, keypair fingerprint, and quotas.

golemdrive account

golemdrive account
golemdrive account --json

usage

Display storage and bandwidth usage.

golemdrive usage

Option	Type	Default	Description
--breakdown	boolean	false	Show usage breakdown by file type

golemdrive usage
golemdrive usage --breakdown --json

password

Change account password.

golemdrive password

Option	Type	Default	Description
--current <password>	string		Current password (prompts if omitted)
--new <password>	string		New password (prompts if omitted)
--confirm <password>	string		Confirm new password (prompts if omitted)

golemdrive password
golemdrive password --current "old" --new "new" --confirm "new"

delete

Schedule account deletion. There is a 60-day restore window before permanent deletion.

golemdrive delete

Option	Type	Default	Description
--confirm	boolean	false	Skip confirmation prompt

golemdrive delete
golemdrive delete --confirm

restore

Cancel a scheduled account deletion.

golemdrive restore

golemdrive restore

stats

Display account and local statistics.

golemdrive stats

Option	Type	Default	Description
--account	boolean	false	Show account-level stats
--local	boolean	false	Show local CLI stats (cache size, temp files)

golemdrive stats --account --json
golemdrive stats --local

---

Search

search

Search files by name and metadata.

golemdrive search <query>

Option	Type	Default	Description
--page <n>	number	1	Page number
--page-size <n>	number	20	Results per page
--type <filter>	string		Filter by type: images, videos, audio, documents, compressed

golemdrive search "tax documents"
golemdrive search "*.pdf" --type documents --page-size 50

---

Keypair Management

keypair list

List available encryption keypairs.

golemdrive keypair list

Option	Type	Default	Description
--user	boolean	false	Show user keypairs only

golemdrive keypair list
golemdrive keypair list --user --json

keypair show

Show details of the active keypair.

golemdrive keypair show

Option	Type	Default	Description
--fingerprint	boolean	false	Show fingerprint only

golemdrive keypair show
golemdrive keypair show --fingerprint

keypair export

Export the current keypair.

golemdrive keypair export

Option	Type	Default	Description
-o, --output <path>	string	stdout	Output file path
--format <type>	string	pem	Export format: pem, json, golemdrive

golemdrive keypair export -o backup.pem
golemdrive keypair export --format json -o keypair.json
golemdrive keypair export --format golemdrive -o keypair.gd

keypair import

Import a keypair from file.

golemdrive keypair import <file>

Option	Type	Default	Description
--force	boolean	false	Overwrite existing keypair without confirmation

golemdrive keypair import backup.pem
golemdrive keypair import keypair.json --force

passphrase setup

Set up a passphrase for keypair encryption.

golemdrive passphrase setup

Option	Type	Default	Description
--strength <level>	string	high	Passphrase strength: standard, high, maximum

golemdrive passphrase setup
golemdrive passphrase setup --strength maximum

passphrase recover

Recover access using a recovery phrase.

golemdrive passphrase recover

Option	Type	Default	Description
--reset	boolean	false	Reset passphrase after recovery

golemdrive passphrase recover
golemdrive passphrase recover --reset

passphrase backup

Generate and display a recovery phrase backup.

golemdrive passphrase backup

Option	Type	Default	Description
--output <path>	string	stdout	Write recovery phrase to file

golemdrive passphrase backup
golemdrive passphrase backup --output recovery.txt

---

Social

profile

View or update your public profile.

golemdrive profile

Option	Type	Default	Description
--display-name <name>	string		Set display name
--bio <text>	string		Set bio
--avatar-url <url>	string		Set avatar URL

golemdrive profile
golemdrive profile --display-name "Jane Doe" --bio "Security researcher"

profile username

Set your public username.

golemdrive profile username <name>

golemdrive profile username janedoe

block

Block a user.

golemdrive block <user-id>

golemdrive block user-uuid

unblock

Unblock a user.

golemdrive unblock <user-id>

golemdrive unblock user-uuid

mute

Mute a user.

golemdrive mute <user-id>

golemdrive mute user-uuid

feed

View your activity feed.

golemdrive feed

Option	Type	Default	Description
--page <n>	number	1	Page number

golemdrive feed --page 2

---

AI Chat

chat

Start an interactive AI chat session or resume an existing one.

golemdrive chat [session-id]

Option	Type	Default	Description
--model <name>	string	default	AI model to use
--no-stream	boolean	false	Disable streaming (wait for complete response)

Opens an interactive REPL. Type exit or press Ctrl+D to quit.

golemdrive chat
golemdrive chat --model glm-5
golemdrive chat session-uuid

chat models

List available AI models.

golemdrive chat models

golemdrive chat models --json

chat sessions

List past chat sessions.

golemdrive chat sessions

golemdrive chat sessions --json

---

Comments

comments list

List comments on a file.

golemdrive comments list <file-uuid>

Option	Type	Default	Description
--limit <n>	number	20	Maximum comments to return
--cursor <token>	string		Pagination cursor from previous response

golemdrive comments list abc123
golemdrive comments list abc123 --limit 50 --json

comments add

Add a comment to a file.

golemdrive comments add <file-uuid> <body>

Option	Type	Default	Description
--reply-to <comment-id>	string		Reply to an existing comment

golemdrive comments add abc123 "Looks good, approved."
golemdrive comments add abc123 "Thanks!" --reply-to comment-uuid

comments delete

Delete a comment.

golemdrive comments delete <comment-id>

Option	Type	Default	Description
--yes	boolean	false	Skip confirmation prompt

golemdrive comments delete comment-uuid
golemdrive comments delete comment-uuid --yes

---

Notifications

notifications list

List notifications.

golemdrive notifications list

Option	Type	Default	Description
--limit <n>	number	20	Maximum notifications to return
--unread	boolean	false	Show unread only

golemdrive notifications list --unread
golemdrive notifications list --limit 50 --json

notifications mark-read

Mark notifications as read. Marks all if no ID is specified.

golemdrive notifications mark-read [id]

golemdrive notifications mark-read
golemdrive notifications mark-read notification-uuid

notifications delete

Delete a notification.

golemdrive notifications delete <id>

Option	Type	Default	Description
--yes	boolean	false	Skip confirmation prompt

golemdrive notifications delete notification-uuid --yes

---

Donations

donate tokens

Donate tokens to a creator. Minimum $0.10.

golemdrive donate tokens <amount>

Option	Type	Default	Description
--message <text>	string		Attach a message to the donation

golemdrive donate tokens 5.00 --message "Great content!"

donate money

Donate money to a creator via Stripe. Minimum $5.00. Returns a Stripe checkout URL.

golemdrive donate money <amount>

golemdrive donate money 10.00

donate history

View your donation history.

golemdrive donate history

golemdrive donate history --json

---

Utility

config set

Set a configuration value.

golemdrive config set <key> <value>

Available keys: api_url, output_format, verbose, color, encrypt_chunk_size, default_concurrency, default_page_size.

golemdrive config set api_url https://api.golemdrive.com
golemdrive config set output_format json
golemdrive config set encrypt_chunk_size 10485760

config get

Get a configuration value.

golemdrive config get <key>

golemdrive config get api_url

config list

List all configuration values.

golemdrive config list

Option	Type	Default	Description
--sources	boolean	false	Show where each value originates (file, env, default)

golemdrive config list --sources

config reset

Reset configuration to defaults.

golemdrive config reset

Option	Type	Default	Description
--force	boolean	false	Skip confirmation prompt

golemdrive config reset --force

config init

Interactive configuration setup wizard.

golemdrive config init

golemdrive config init

cleanup

Clean up temporary and cached files.

golemdrive cleanup

Option	Type	Default	Description
--temp	boolean	false	Remove temporary upload/download files
--cache	boolean	false	Clear cached metadata
--stale	boolean	false	Remove stale lock files
--old	boolean	false	Remove files older than 30 days
--force	boolean	false	Skip confirmation prompt
--dry-run	boolean	false	Show what would be removed without deleting

golemdrive cleanup --temp --cache --dry-run
golemdrive cleanup --stale --old --force

signature

Display the MD5 signature of a file for integrity verification.

golemdrive signature <file-uuid>

Option	Type	Default	Description
--copy	boolean	false	Copy signature to clipboard

golemdrive signature abc123
golemdrive signature abc123 --copy

version

Display CLI version.

golemdrive version

examples

Show usage examples for common workflows.

golemdrive examples

help

Show help for a specific topic or command.

golemdrive help [topic]

golemdrive help
golemdrive help upload
golemdrive help share

---

Environment Variables

All environment variables are optional and override their corresponding config file values and flags.

Variable	Description
GD_API_URL	API base URL (e.g., https://api.golemdrive.com)
GD_USERNAME	Username for non-interactive authentication
GD_PASSWORD	Password for non-interactive authentication
GD_TOKEN	Pre-authenticated JWT token
GD_PASSPHRASE	Default encryption passphrase
GD_SHARE_PASSWORD	Default share link password
GD_VERBOSE	Enable verbose output (true or 1)
GD_OUTPUT_FORMAT	Default output format (json or table)
OIDC_PROVIDER_URL	OIDC provider base URL
OIDC_REALM	OIDC realm name
OIDC_CLIENT_ID	OIDC client ID for authentication

Precedence

Configuration values are resolved in this order (highest to lowest priority):

1. Command-line flags (--api-url, --json, etc.)
2. Environment variables (GD_API_URL, etc.)
3. Config file (~/.golemdrive/config.json)
4. Built-in defaults