CarbonFiles.Cli 0.2.5

CarbonFiles CLI (cf)

A colorful command-line tool for managing CarbonFiles -- buckets, files, API keys, tokens, and more. Built with Spectre.Console for rich terminal output.

Installation

dotnet tool (requires .NET 10)

dotnet tool install -g CarbonFiles.Cli

From source

git clone <repo-url>
cd carbon-cli
dotnet build

Quick Start

# Configure your server
cf config set --url https://files.example.com --token cf4_your_api_key

# Create a bucket
cf bucket create "My Files" -e 7d

# Upload files
cf file upload <bucket-id> ./document.pdf ./image.png

# List your buckets
cf bucket list

# Download a file
cf file download <bucket-id> document.pdf

Command Reference

Configuration

The CLI stores its configuration in ~/.cf/config.json. Configuration is organized into named profiles, allowing you to connect to multiple CarbonFiles servers or use different credentials.

Setting up a profile

# Configure the default profile
cf config set --url https://files.example.com --token cf4_your_api_key

# Create a named profile
cf config set --profile staging --url https://staging.example.com --token cf4_staging_key

Managing profiles

# List all profiles
cf config profiles

# Switch the active profile
cf config use staging

# Show current profile configuration
cf config show

Per-command profile override

Any command accepts the --profile flag to use a specific profile without switching the active one:

cf bucket list --profile staging

Global Options

Examples

Create a bucket with an expiry

cf bucket create "Sprint Demo" -d "Files for the sprint review" -e 7d

Upload a directory recursively

cf file upload abc123 ./build-output/ -r

Pipe content from stdin

echo "Hello, world!" | cf file upload abc123 --stdin -n greeting.txt

Use JSON output with jq

# Get all bucket IDs
cf bucket list --json | jq '.[].id'

# Get the total size of a bucket
cf bucket info abc123 --json | jq '.total_size'

Create an upload token and use it

# Create a token that allows 10 uploads and expires in 1 hour
cf token create upload abc123 -e 1h --max-uploads 10

# Use the token to upload (instead of your API key)
cf file upload abc123 ./photo.jpg --token cfu_the_upload_token

Watch a bucket for live changes

cf bucket watch abc123

This opens a live SignalR connection and streams file created, updated, and deleted events as they happen. Press Ctrl+C to stop.

Download a file to a specific path

cf file download abc123 reports/q4.pdf -o ~/Downloads/q4-report.pdf

Download an entire bucket as a ZIP

cf bucket download abc123

Development

# Build
dotnet build

# Run tests
dotnet test

# Run a CLI command during development
dotnet run --project src/CarbonFiles.Cli -- <command>