DocShare CLI¶

A fast, single-binary command-line interface for managing files on your DocShare server.

Table of Contents¶

Installation
Quick Start
Authentication
Commands
General
Files
Upload & Download
Sharing
Transfer
Path Resolution
Global Flags
Configuration
Shell Completion
Examples
Building from Source

Installation¶

One-line install (recommended)¶

curl -sSfL https://raw.githubusercontent.com/hayward-solutions/docshare/main/cli/install.sh | sh

This will: 1. Download the pre-built binary for your OS and architecture from GitHub Releases 2. Fall back to building from source if no binary is available (requires Go 1.24+) 3. Install to /usr/local/bin/docshare

Install to a custom directory:

curl -sSfL https://raw.githubusercontent.com/hayward-solutions/docshare/main/cli/install.sh | sh -s -- --dir ~/.local/bin

Install a specific version:

curl -sSfL https://raw.githubusercontent.com/hayward-solutions/docshare/main/cli/install.sh | sh -s -- --version v1.0.0

Homebrew (macOS/Linux)¶

Coming soon.

Manual download¶

Download a pre-built binary from GitHub Releases, extract it, and place it somewhere on your PATH:

tar -xzf docshare_*_linux_amd64.tar.gz
sudo mv docshare /usr/local/bin/

Build from source¶

Requires Go 1.24+:

git clone https://github.com/hayward-solutions/docshare.git
cd docshare/cli
go build -o docshare .
sudo mv docshare /usr/local/bin/

Quick Start¶

# 1. Point to your server (skip if using localhost:8080)
docshare login --server https://docshare.example.com

# 2. Authenticate
docshare login

# 3. Start using it
docshare ls
docshare upload report.pdf
docshare download /Documents/report.pdf

Authentication¶

DocShare CLI supports two authentication methods.

Device flow (default)¶

The device flow opens your browser to approve the CLI session. This is the recommended method for interactive use.

docshare login

The CLI will: 1. Request a device code from the server 2. Open your browser to the approval page 3. Display a user code (e.g. BCDF-GHJK) in case the browser doesn't open 4. Poll until you approve, then save the token

API token¶

For scripting or headless environments, use an API token. Generate one in the DocShare web UI under Settings > API Tokens, then:

docshare login --token dsh_7f8e9d0c1b2a3948576d5e4f...

The token is validated against the server and saved to your local config.

Verify authentication¶

docshare whoami

Log out¶

docshare logout

This removes the stored token from your machine.

Version & Updates¶

Check version¶

docshare version

Shows the CLI version, server version, and API version. The server endpoint is unauthenticated — works before login.

Example output:

CLI version:    v0.1.0
Server version: v0.1.0
API version:    v1

Upgrade to latest release¶

docshare upgrade

Downloads and installs the latest release from GitHub automatically. This command: - Checks your current version against the latest GitHub release - Downloads the appropriate binary for your OS/architecture - Replaces the current binary in-place with atomic backup/restore - Preserves your configuration

Notes: - Only works with release versions (not dev builds) - Requires write access to the CLI binary location - If installed via package manager, use that to upgrade instead

Commands¶

General¶

`version` — Show version information¶

docshare version
docshare version --json

Displays CLI version, server version, and API version. Works without authentication.

`upgrade` — Upgrade to latest release¶

docshare upgrade

Automatically downloads and installs the latest release. Only works with release builds.

Files¶

`ls` — List files and directories¶

docshare ls                          # List root directory
docshare ls /Documents               # List folder by path
docshare ls /Documents --sort name   # Sort by name, createdAt, or size
docshare ls /Documents --order desc  # Sort descending

Flags: | Flag | Description | |------|-------------| | --sort | Sort field: name, createdAt, size | | --order | Sort order: asc, desc |

`info` — File details¶

docshare info /Documents/report.pdf

Displays name, ID, type, size, owner, share count, and timestamps.

`search` — Search by name¶

docshare search "quarterly report"

`mkdir` — Create a directory¶

docshare mkdir "My Documents"                  # Create in root
docshare mkdir Reports /Documents              # Create inside a folder
docshare mkdir /Documents/Reports/Q1           # Create with full path
docshare mkdir Reports --parent <folder-id>    # Create by parent ID

`rm` — Delete a file or directory¶

docshare rm /Documents/old-report.pdf          # Prompts for confirmation
docshare rm /Temp --force                      # Skip confirmation

Deleting a directory removes all contents recursively. This cannot be undone.

`mv` — Move or rename¶

docshare mv /Documents/report.pdf /Archive     # Move to different folder
docshare mv /Documents/old.pdf new-name.pdf    # Rename

If the destination resolves to an existing directory, the file is moved into it. Otherwise, the file is renamed.

Upload & Download¶

`upload` — Upload files and directories¶

Single file:

docshare upload report.pdf                     # Upload to root
docshare upload report.pdf /Documents          # Upload to a folder

Directory (recursive):

docshare upload ./project/ /Documents          # Uploads all files and recreates directory structure
docshare upload ./project/ /Documents -w 8     # Use 8 concurrent upload workers

Directory uploads create the remote folder structure automatically and upload files in parallel using a worker pool (default: 4 workers).

Flags: | Flag | Description | |------|-------------| | --parent | Parent folder ID (alternative to positional path argument) | | -w, --workers | Number of concurrent upload workers for directories (default: 4) |

`download` — Download files and directories¶

Single file:

docshare download /Documents/report.pdf            # Download to current directory
docshare download /Documents/report.pdf ./out       # Download to specific directory
docshare download /Documents/report.pdf -o my.pdf   # Download with custom filename

Directory (recursive):

docshare download /Projects                         # Download entire folder tree
docshare download /Projects ./backup                # Download to specific directory

Downloads use presigned URLs to stream directly from object storage, bypassing the backend for maximum throughput.

Flags: | Flag | Description | |------|-------------| | -o, --output | Output file path (overrides default naming) |

`share` — Share a file with a user¶

docshare share /Documents/report.pdf alice@example.com
docshare share /Documents/report.pdf alice@example.com --permission edit

The CLI looks up the user by email via the API. Permission levels: - view — Can see metadata and preview - download — Can download the file (default) - edit — Can modify and reshare

Flags: | Flag | Description | |------|-------------| | --permission | Permission level: view, download, edit (default: download) |

`unshare` — Revoke a share¶

docshare unshare <share-id>

Use docshare info <file> or the web UI to find share IDs.

`shared` — List files shared with you¶

docshare shared

Transfer¶

Transfer files securely between users using short-lived transfer codes. Both sender and receiver must be authenticated.

`transfer send` — Send a file¶

docshare transfer send report.pdf
docshare transfer send ./folder/file.txt --timeout 10m

Creates a transfer and waits for a receiver to connect. The sender's file is only uploaded after the receiver has connected.

Flags: | Flag | Description | |------|-------------| | --timeout | How long to wait for receiver (e.g., 5m, 10m, 1h). Default: 5m |

`transfer receive` — Receive a file¶

docshare transfer receive ABC123
docshare transfer receive ABC123 --output ./Downloads

Connects to a transfer using a code and downloads the file.

Flags: | Flag | Description | |------|-------------| | -o, --output | Output directory for received file (default: current directory) |

`transfer list` — List pending transfers¶

docshare transfer list

Shows pending transfers you've initiated that are waiting for a receiver.

`transfer cancel` — Cancel a transfer¶

docshare transfer cancel ABC123

Cancels a pending transfer. Only the sender can cancel.

Path Resolution¶

Most commands accept remote paths in two formats:

Human-readable paths resolve folder names by walking the directory tree:

docshare ls /Documents/Projects/2025
docshare download /Documents/Projects/2025/report.pdf

Path matching is case-insensitive.

UUIDs are passed through directly (useful for scripting):

docshare ls 550e8400-e29b-41d4-a716-446655440000
docshare download 770e8400-e29b-41d4-a716-446655440003

Global Flags¶

These flags are available on every command:

Flag	Description
`--json`	Output as JSON (useful for scripting and piping)
`--server`	Override server URL for this command
`-h`, `--help`	Show help for any command

JSON output example:

docshare ls --json | jq '.[].name'
docshare info /Documents/report.pdf --json | jq '.size'

Configuration¶

The CLI stores its configuration in ~/.config/docshare/config.json:

{
  "server_url": "http://localhost:8080",
  "token": "dsh_7f8e9d..."
}

Field	Description
`server_url`	Base URL of your DocShare server
`token`	Authentication token (API token or JWT from device flow)

The config file is created automatically on docshare login. You can also edit it directly.

Override the server URL per-command:

docshare --server https://other-server.com ls

Shell Completion¶

Generate shell completions for tab-completion of commands, subcommands, and flags.

Zsh¶

# If using Oh My Zsh:
docshare completion zsh > ~/.oh-my-zsh/completions/_docshare

# Otherwise, use a directory in your fpath:
docshare completion zsh > /usr/local/share/zsh/site-functions/_docshare

Then restart your shell or run source ~/.zshrc.

Bash¶

# macOS (Homebrew bash-completion):
docshare completion bash > /usr/local/etc/bash_completion.d/docshare

# Linux:
docshare completion bash > /etc/bash_completion.d/docshare

Then restart your shell or run source ~/.bashrc.

Fish¶

docshare completion fish > ~/.config/fish/completions/docshare.fish

Completions are picked up automatically on the next shell session.

PowerShell¶

docshare completion powershell > docshare.ps1
. ./docshare.ps1

To load completions on every session, add the output to your PowerShell profile ($PROFILE).

Examples¶

Back up a remote directory locally¶

docshare download /Documents ./backup-$(date +%Y%m%d)

Upload an entire project¶

docshare mkdir "Project Alpha"
docshare upload ./src /Project\ Alpha -w 8

List all files as JSON and filter with jq¶

# Find all PDFs
docshare ls --json | jq '[.[] | select(.mimeType == "application/pdf")]'

# Total size of all files
docshare ls --json | jq '[.[].size] | add'

docshare share /Documents/Shared alice@example.com --permission download

Scripting with API tokens¶

export DOCSHARE_TOKEN="dsh_..."
docshare login --token "$DOCSHARE_TOKEN"
docshare upload ./reports/*.pdf /Monthly\ Reports

Use with a remote server¶

docshare --server https://files.example.com login
docshare --server https://files.example.com ls

Or set it once:

docshare login --server https://files.example.com
# Server URL is now saved — no need to repeat it
docshare ls

Building from Source¶

# Clone
git clone https://github.com/hayward-solutions/docshare.git
cd docshare/cli

# Build
go build -o docshare .

# Build with optimizations (smaller binary)
CGO_ENABLED=0 go build -ldflags="-s -w" -o docshare .

# Run tests
go vet ./...

# Install globally
sudo mv docshare /usr/local/bin/

Cross-compile for other platforms:

GOOS=linux   GOARCH=amd64 go build -ldflags="-s -w" -o docshare-linux-amd64 .
GOOS=linux   GOARCH=arm64 go build -ldflags="-s -w" -o docshare-linux-arm64 .
GOOS=darwin  GOARCH=amd64 go build -ldflags="-s -w" -o docshare-darwin-amd64 .
GOOS=darwin  GOARCH=arm64 go build -ldflags="-s -w" -o docshare-darwin-arm64 .
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o docshare-windows-amd64.exe .