CLI C# Documentation

Sharokey CLI is a command-line tool for creating, managing and sharing secrets securely with Zero Knowledge encryption.

🚀 Quick Start

# 1. Configure your token (only required step)
sharokey config --token your_token_here

# 2. Create your first secret
sharokey create "My first secret" --hours 24 --views 1

# 3. List your secrets
sharokey list

📦 Installation

1. Download the sharokey.exe file
2. Place it in a folder accessible via your PATH
3. Configure your authentication token (only configuration required)

⚙️ Configuration

Initial Configuration

# Minimal configuration - set your authentication token
sharokey config --token your_token_here

# Check configuration
sharokey config --show

That's it! The API URL is built into the CLI, no additional configuration is needed.

Advanced Configuration Options (optional)

sharokey config --token <token>              # Authentication token (REQUIRED)
sharokey config --default-hours <hours>      # Default expiration hours (1-1000)
sharokey config --default-views <views>      # Default max views (1-10)
sharokey config --timeout <seconds>          # Request timeout (5-300 seconds)
sharokey config --logs-enabled               # Enable/disable logging
sharokey config --log-level <level>          # Log level (Debug, Information, Warning, Error)
sharokey config --disable-ssl-validation     # Disable SSL validation (dev only)

💼 Usage

Create a Secret

Basic Creation

# Create a simple secret
sharokey create "My secret message" --hours 24 --views 1

# With description, message, and email OTP
sharokey create "Password: admin123" --hours 6 --views 3 --description "Server access" --message "Use carefully" --otp-email "[email protected]"

# With SMS OTP (mutually exclusive with email OTP)
sharokey create "Password: admin123" --hours 6 --views 3 --description "Server access" --otp-phone "+33674747474"

# With password protection and CAPTCHA
sharokey create "Confidential information" --hours 12 --views 2 --password "password123" --captcha

# With attachments (max 10 files, 10MB total)
sharokey create "Monthly report" --hours 48 --views 5 --attach report.pdf --attach annex.docx --description "Confidential documents"

# With multiple files and IP restriction
sharokey create "Complete folder" --hours 24 --views 3 --attach contract.pdf --attach signature.png --attach terms.docx --description "Client XYZ contract" --ip-whitelist "192.168.1.0/24,10.0.0.1"

Advanced Security Options

# With CAPTCHA verification
sharokey create "Secure data" --hours 2 --views 1 --captcha --description "Protected content"

# IP whitelist (CIDR or individual IPs)
sharokey create "Internal docs" --hours 24 --views 5 --ip-whitelist "192.168.1.0/24,10.0.0.1,203.0.113.5"

# Geolocation restriction (ISO country codes)
sharokey create "EU only data" --hours 48 --views 3 --geolocation "FR,DE,BE,ES,IT"

# Combined security: CAPTCHA + IP + Geo + OTP
sharokey create "Maximum security" --hours 6 --views 1 --captcha --ip-whitelist "192.168.1.0/24" --geolocation "FR,US" --otp-email "[email protected]"

Random Password Generation

# Generate a random 16-character password
sharokey create --generate-password --password-length 16 --hours 1 --views 1

# 32-character password with security options
sharokey create --generate-password --password-length 32 --hours 24 --views 5 --captcha --geolocation "FR,US,CA"

Reading from stdin

# Read content from stdin
echo "Secret from stdin" | sharokey create --hours 2 --views 1

# From a file
cat secret.txt | sharokey create --hours 48 --views 10

List Secrets

# List all secrets (default limit: 50)
sharokey list

# Limit number of results (1-500)
sharokey list --limit 10

# Filter by status
sharokey list --status active
sharokey list --status expired

# Filter by creator
sharokey list --creator [email protected]

# Combine filters
sharokey list --status active --creator [email protected] --limit 5

View Secret Details

# Show secret details
sharokey get ABC123XYZ

# Verbose mode with more information
sharokey get ABC123XYZ --verbose

Delete a Secret

# Delete a secret
sharokey delete ABC123XYZ

Statistics

# Show global statistics
sharokey stats

🎛️ Global Options

Output Format

Default: JSON Format (ideal for scripts and automation)

sharokey list
# Output: {"success": true, "count": 2, "secrets": [{"slug": "ABC123", "maximum_views": 1, ...}]}

sharokey create "test" --hours 1 --views 1
# Output: {"slug": "ABC123", "share_url": "https://...", "expires_in_hours": 1, ...}

Option --table: Human-readable format (ideal for interactive use)

sharokey list --table
# Output:
# slug     description                    creator    maximum_views current_views expiration
# -----------------------------------------------------------------------------------------
# ABC123   My test secret                 API        1             0             2025-08-08...

sharokey create "test" --hours 1 --views 1 --table
# Output:
# ✅ Secret created successfully!
# slug     share_url                      expires_in_hours maximum_views ...
# ---------------------------------------------------------------------------------
# ABC123   https://api.sharokey.com/... 1                1            ...

Output Fields

Standardized fields (identical in JSON and table formats):

• slug: Unique secret identifier
• description: Secret description
• creator: Creator email
• maximum_views: Maximum allowed views
• current_views: Current view count
• expiration: Expiration date in ISO format
• created_at: Creation date in ISO format
• has_attachments: Has attachments (true/false)
• expires_in_hours: Hours until expiration (creation only)

Verbose Mode

# Detailed output with debug information
sharokey create "test" --hours 1 --views 1 --verbose
sharokey list --verbose

📋 Detailed Parameters

Expiration Duration (--hours)

• Minimum: 1 hour
• Maximum: 1000 hours
• Default: 24 hours
• Format: Integer representing hours

View Count (--views)

• Minimum: 1 view
• Maximum: 10 views
• Default: 1 view
• Format: Integer representing maximum consultations

Generated Password Length (--password-length)

• Minimum: 8 characters
• Maximum: 32 characters
• Default: 16 characters

Security Options

Two-Factor Authentication (OTP)

• --otp-email: Email address for OTP code delivery
• --otp-phone: Phone number in international format (e.g., +33674747474)
• Restriction: --otp-email and --otp-phone are mutually exclusive
• Purpose: Adds an additional security layer requiring a one-time code

Access Control

• --captcha: Enable CAPTCHA verification before secret access
• --ip-whitelist: Comma-separated list of allowed IP addresses or CIDR blocks (max 255 characters)
  • Format: 192.168.1.100,10.0.0.0/24,203.0.113.5
  • Maximum length: 255 characters
• --geolocation: Comma-separated list of allowed country codes (ISO 3166-1 alpha-2, max 255 characters)
  • Format: FR,US,CA,DE,BE
  • Maximum length: 255 characters

Additional Fields

• --message: Custom message displayed to the secret viewer
  • Maximum length: 500 characters
  • Purpose: Provide context or instructions to the recipient

Attachments (--attach)

• Usage: --attach file1.pdf --attach file2.docx
• Maximum files: 10 files per secret
• Maximum total size: 10MB for all files combined
• Encryption: Each file is individually encrypted with the same keys as the main content
• Supported formats: All file types are supported (files are encrypted before transmission)

📧 Secret Requests

Ask others to share secrets with you securely through generated request URLs.

Create a Secret Request

# Basic secret request
sharokey create-request --message "Please share the database credentials" --description "Production DB access"

# With expiration times and view limits
sharokey create-request --message "Share VPN config" --description "Remote access setup" --secret-hours 24 --request-hours 48 --max-views 1

# With email delivery
sharokey create-request --message "Please provide API keys" --description "Integration setup" --email-to "[email protected]" --email-reply "[email protected]"

# Complete example with all options
sharokey create-request \
  --message "Please share the production credentials securely" \
  --description "Q4 deployment access needed" \
  --secret-hours 24 \
  --request-hours 48 \
  --max-views 1 \
  --email-to "[email protected]" \
  --email-reply "[email protected]"

List Secret Requests

# List all requests
sharokey list-requests

# Filter by status
sharokey list-requests --status active

# Limit results
sharokey list-requests --limit 10

# Combined filters
sharokey list-requests --status active --limit 5

Get Request Details

# Get details for a specific request by ID
sharokey get-request 123

Delete a Request

# Delete and invalidate a request
sharokey delete-request 123

Request Statistics

# Get statistics about your secret requests
sharokey request-stats

Secret Request Parameters

Parameter	Description	Default	Required
--message	Message displayed to the recipient	None	No
--description	Internal description for your reference	None	No
--secret-hours	Hours until shared secret expires	24	No
--request-hours	Hours until request expires	48	No
--max-views	Maximum views for shared secret (1-10)	1	No
--email-to	Email to send request to	None	No
--email-reply	Reply-to email for notifications	None	No

🔐 Security

Zero Knowledge Encryption

• Client-side encryption: Your content is encrypted before transmission
• Split key: Decryption key is included in the URL (fragment #)
• No key storage: Server can never decrypt your secrets
• Algorithm: AES-GCM-256 with PBKDF2 (10,000 iterations)

Best Practices

• Sensitive URLs: Never share the complete URL publicly
• Limited duration: Use short expiration times
• Limited views: Restrict the number of consultations
• Password protection: Add additional protection for critical data

💾 Configuration Storage

Location

• Windows: %APPDATA%\Sharokey\config.json
• Linux/Mac: ~/.config/sharokey/config.json

Token Security

The authentication token is encrypted and stored securely on your local system.

⚠️ Error Codes

• Code 1: API error (authentication, validation, server)
• Code 3: Network or communication error
• Code 4: Initialization error (missing configuration)
• Code 5: Parameter validation error
• Code 10: Secret not found

🆘 Support and Troubleshooting

Check Configuration

sharokey config --show

Test Connectivity

sharokey stats

Debug Logging

# Enable detailed logs
sharokey config --log-level Debug --logs-enabled

# Use verbose mode
sharokey create "test" --hours 1 --views 1 --verbose

Common Issues

1. Authentication error: Check your token with sharokey config --show
2. Timeout: Increase timeout with sharokey config --timeout 60
3. Secret not found: Verify the slug is correct and the secret hasn't expired

Simplified Configuration

✅ Simpler: Only the token is required to get started
✅ Built-in URL: API URL is hardcoded in the CLI
✅ Ready to use: Download, configure token, use

📖 Version and Help

# Show general help
sharokey --help

# Help for specific commands  
sharokey create --help
sharokey list --help
sharokey config --help

🔄 Command Reference

sharokey create

Purpose: Create a new encrypted secret

Syntax:

sharokey create [content] --hours <1-1000> --views <1-10> [OPTIONS]

Required Options:

• --hours: Expiration time in hours (1-1000)
• --views: Maximum number of views (1-10)

Optional Options:

• --description: Secret description
• --message: Custom message for viewer (max 500 chars)
• --password: Additional password protection
• --captcha: Enable CAPTCHA verification
• --ip-whitelist: Allowed IP addresses/CIDR blocks (comma-separated)
• --geolocation: Allowed country codes (comma-separated, ISO format)
• --otp-email: Email for OTP authentication
• --otp-phone: Phone for SMS OTP (mutually exclusive with email)
• --attach: Attach files (can be used multiple times)
• --generate-password: Generate random password instead of content
• --password-length: Length of generated password (8-32, default: 16)
• --table: Output in table format
• --verbose: Verbose output

sharokey list

Purpose: List your secrets

Syntax:

sharokey list [OPTIONS]

Options:

• --limit: Maximum results (1-500, default: 50)
• --status: Filter by status (active, expired)
• --creator: Filter by creator email
• --table: Output in table format
• --verbose: Verbose output

sharokey get

Purpose: Get details of a specific secret

Syntax:

sharokey get <slug> [OPTIONS]

Options:

• --verbose: Show additional details

sharokey delete

Purpose: Delete a secret

Syntax:

sharokey delete <slug>

sharokey stats

Purpose: Show usage statistics

Syntax:

sharokey stats

sharokey config

Purpose: Configure CLI settings

Syntax:

sharokey config [OPTIONS]

Options:

• --token: Set authentication token (required)
• --default-hours: Default expiration hours (1-1000)
• --default-views: Default max views (1-10)
• --timeout: Request timeout seconds (5-300)
• --logs-enabled: Enable/disable logging
• --log-level: Log level (Debug, Information, Warning, Error)
• --disable-ssl-validation: Disable SSL validation (dev only)
• --show: Show current configuration

---

Sharokey CLI - Secure secret sharing with Zero Knowledge encryption