CLI Documentation

Sharokey CLI is a command-line tool for managing encrypted secrets with Zero Knowledge architecture.

Installation

bash

# Download and configure
curl -L https://github.com/Sharokey/sharokey-cli/releases/latest/download/sharokey.exe -o sharokey.exe
sharokey config --token your_api_token_here
sharokey test

Commands

Command	Description	Example
`create`	Create encrypted secret	`sharokey create "password" --hours 24 --views 1`
`list`	List secrets	`sharokey list --limit 10 --status active`
`get`	Get secret details	`sharokey get ABC123`
`delete`	Expire secret (clears content)	`sharokey delete ABC123`
`stats`	Show statistics	`sharokey stats`
`config`	Configure settings	`sharokey config --token TOKEN`
`test`	Test connectivity	`sharokey test`

Secret Requests

Command	Description	Example
`create-request`	Create secret request	`sharokey create-request --message "Share credentials" --secret-hours 24 --request-hours 48 --max-views 1 --locale fr`
`list-requests`	List requests (most recent first)	`sharokey list-requests --status active --limit 10`
`get-request`	Get request details	`sharokey get-request abc123token456`
`delete-request`	Expire request (cancels)	`sharokey delete-request abc123token456`
`request-stats`	Request statistics	`sharokey request-stats`

Parameters

Create Secret

Parameter	Description	Example
`--hours`	Expiration hours (1-1000)	`--hours 48`
`--views`	Maximum views (1-10)	`--views 3`
`--description`	Secret description (max 255 chars)	`--description "DB credentials"`
`--message`	Viewer message (max 255 chars)	`--message "Use carefully"`
`--password`	Additional protection (4-100 chars)	`--password "secret123"`
`--captcha`	Enable CAPTCHA verification	`--captcha`
`--otp-email`	OTP via email (valid email format)	`--otp-email [email protected]`
`--otp-phone`	OTP via SMS (international format)	`--otp-phone +33674747474`
`--ip-whitelist`	Allowed public IPs (max 255 chars)	`--ip-whitelist "203.0.113.5,198.51.100.10"`
`--geolocation`	Allowed countries ISO codes (max 255 chars)	`--geolocation "FR,US,DE"`
`--attach`	Attach files (max 10 files, 10MB total)	`--attach file.pdf --attach doc.docx`

Security Priority

If multiple security options are specified, only the highest level is applied:
captcha < password < otp-email < otp-phone (highest)

Example: --password "secret" --captcha --otp-phone "+33123456789" → Only OTP phone will be used

Configuration

Parameter	Description	Example
`--token`	API token (required)	`--token abcd1234...`
`--timeout`	Request timeout (5-300s)	`--timeout 60`
`--logs-enabled`	Enable logging	`--logs-enabled`
`--log-level`	Log level (Debug, Information, Warning, Error)	`--log-level Debug`
`--show`	Show current config	`--show`

Output Format

Parameter	Description
`--table`	Human-readable table
Default	JSON format

Examples

Basic Usage

bash

# Simple secret
sharokey create "Database password: admin123" --hours 24 --views 1

# With description and message
sharokey create "API credentials" --description "Production API access" --message "Valid until project end" --hours 48 --views 3

# CAPTCHA protection
sharokey create "Server access" --captcha --hours 12 --views 1

# Password protection  
sharokey create "Sensitive data" --password "mySecretPass123" --hours 6 --views 2

# OTP email protection (higher priority than password)
sharokey create "Bank details" --password "backup" --otp-email "[email protected]" --hours 24 --views 1

# OTP SMS protection (highest priority - will override all others)
sharokey create "Critical access" --password "backup" --captcha --otp-email "[email protected]" --otp-phone "+33674747474" --hours 2 --views 1

# IP restriction (public IPs only)
sharokey create "External access" --ip-whitelist "203.0.113.5,198.51.100.10" --hours 48 --views 10

# Geolocation restriction
sharokey create "EU only data" --geolocation "FR,DE,BE,IT,ES" --hours 72 --views 5

# Combined restrictions
sharokey create "Restricted access" --password "secure123" --ip-whitelist "203.0.113.100" --geolocation "FR,US" --hours 24 --views 2

# With attachments
sharokey create "Contract files" --attach contract.pdf --attach terms.pdf --description "Client XYZ documents" --hours 48 --views 5

# Multiple attachments with security
sharokey create "Confidential reports" --attach report.pdf --attach data.xlsx --attach summary.docx --password "reports2024" --ip-whitelist "203.0.113.50,198.51.100.25" --hours 168 --views 3

# Read from stdin
echo "Secret from command line" | sharokey create --hours 2 --views 1
cat credentials.txt | sharokey create --description "Server credentials" --password "access123" --hours 48 --views 1

Secret Requests

bash

# Create request with email delivery (JSON output by default - direct API response)
sharokey create-request --message "Please share VPN credentials" --email-to [email protected] --email-reply [email protected] --request-hours 48 --secret-hours 24 --max-views 3 --locale fr

# Create request with table output
sharokey create-request --message "Share credentials" --email-to [email protected] --request-hours 24 --secret-hours 12 --max-views 1 --locale en --table

# Get request details by token (JSON by default - direct API response)
sharokey get-request abc123token456

# Get request details in table format
sharokey get-request abc123token456 --table

# List requests with filters (JSON by default - direct API response, most recent first)
sharokey list-requests --status active --limit 20

# List requests in table format (most recent first)
sharokey list-requests --status active --limit 20 --table

# Expire request by token (cancels and makes it inactive)
sharokey delete-request abc123token456

# View request statistics (JSON only - direct API response)
sharokey request-stats

# Request parameters: --secret-hours (1-1000), --request-hours (1-1000), --max-views (1-10)
# Email fields: --email-to and --email-reply (valid email format required)
# Locale: --locale (en or fr) - sets email language when sending notifications
# Limit returns most recent requests first (sorted by created_at desc)

Management

bash

# List all secrets
sharokey list

# List with filters
sharokey list --status active --creator [email protected] --limit 20
sharokey list --status expired --limit 10

# JSON output (default)
sharokey list --limit 5
# Output: {"success": true, "count": 2, "secrets": [{"slug": "ABC123", "maximum_views": 1, ...}]}

# Table output (human-readable)
sharokey list --table --limit 5
# Output:
# slug     description                    creator    maximum_views current_views expiration
# -----------------------------------------------------------------------------------------
# ABC123   My test secret                 API        1             0             2025-08-08...

# List secrets with limit
sharokey list --limit 3

# Get secret details
sharokey get ABC123

# Expire secret (clears content, forces expiration)
sharokey delete ABC123

# Statistics
sharokey stats

Limits & Constraints

Content & Text

Secret content: 255 characters max (before encryption)
Description: 255 characters max
Message: 255 characters max
Password: 4-100 characters
IP whitelist: 255 characters max (public IPs only, comma-separated)
Geolocation: 255 characters max (ISO country codes)

Attachments

Maximum files: 10 per secret
Total size: 10MB across all files
Supported formats: Documents (pdf, txt, docx, doc, xlsx, xls, pptx, ppt, rtf, odt, ods, odp), Images (jpg, jpeg, png, gif, bmp, webp, svg), Audio (mp3, wav, flac, m4a, aac, ogg), Video (mp4, avi, mkv, mov, wmv, webm), Archives (zip, rar, 7z, tar, gz)
Encryption: Files encrypted client-side before upload

Time & Access

Expiration: 1-1000 hours
Maximum views: 1-10 views

Security

Zero Knowledge Architecture

Client-side encryption: AES-GCM-256 with PBKDF2 (10,000 iterations)
Split keys: KeyA (sent to server) + KeyB (in URL fragment)
No server access: Server cannot decrypt secrets
Perfect Forward Secrecy: Keys never stored server-side

Best Practices

Use short expiration times for sensitive data
Limit view counts appropriately
Choose appropriate security level: OTP phone (highest) > OTP email > password > CAPTCHA
Combine with IP restrictions (public IPs) and geo restrictions for access control
Only the highest security level will be applied if multiple are specified

Configuration Storage

Windows: %APPDATA%\Sharokey\config.json
Linux/Mac: ~/.config/sharokey/config.json
Token encryption: Stored encrypted using OS data protection

Error Codes

Code	Description
0	Success
1	API error (authentication, validation, server)
3	Network error
4	Configuration error
5	Parameter validation error
10	Secret not found

Test & Diagnostics

Connectivity Test

The test command performs comprehensive client-side diagnostics:

bash

# Full connectivity test (6 tests)
sharokey test

# Quick test (config + network only)
sharokey test --quick

# Verbose output with details
sharokey test --verbose

Test Details:

Configuration - Validates API token presence
Network - Ping test + HTTP connectivity to API
Authentication - Verifies token validity with API
Read Permissions - Tests secret listing capability
Statistics - Tests stats endpoint access
Write Permissions - Currently skipped (avoids test secrets)

Output Format:

Exit code: 0 = success, 1 = failure
Console display with status emojis and colors

Test Command Details

The test command performs comprehensive client-side diagnostics including server health verification, authentication validation, and permission checks. This goes beyond a simple server status check to ensure full functionality.

Troubleshooting

bash

# Check configuration
sharokey config --show

# Test connectivity  
sharokey test

# Enable debug logging
sharokey config --log-level Debug --logs-enabled

Common issues:

Authentication error: Check token with sharokey config --show
Timeout: Increase with sharokey config --timeout 60
Secret not found: Verify slug and expiration status
Validation failed: Check parameter limits (secret content ≤255 chars, message ≤255 chars, geolocation ≤255 chars, etc.)
Attachment error: Verify file formats (40+ supported formats including documents, images, audio, video, archives) and 10MB total limit
OTP format error: Use international format for phone (+33674747474)
IP whitelist error: Only public IP addresses are supported, no CIDR blocks or private IPs

Python SDK - Python library with async support
JavaScript CDN - Lightweight browser version
Response Structures - Complete JSON response documentation
Feature Comparison - Compare all Sharokey libraries

CLI Documentation ​

Installation ​

Commands ​

Secret Requests ​

Parameters ​

Create Secret ​

Configuration ​

Output Format ​

Examples ​

Basic Usage ​

Secret Requests ​

Management ​

Limits & Constraints ​

Content & Text ​

Attachments ​

Time & Access ​

Security ​

Zero Knowledge Architecture ​

Best Practices ​

Configuration Storage ​

Error Codes ​

Test & Diagnostics ​

Connectivity Test ​

Troubleshooting ​

Related Resources ​

CLI Documentation

Installation

Commands

Secret Requests

Parameters

Create Secret

Configuration

Output Format

Examples

Basic Usage

Secret Requests

Management

Limits & Constraints

Content & Text

Attachments

Time & Access

Security

Zero Knowledge Architecture

Best Practices

Configuration Storage

Error Codes

Test & Diagnostics

Connectivity Test

Troubleshooting

Related Resources