These docs track the development branch (main). Latest release: v0.38.2.
CargoShip

Appearance

Diagnostics & utilities ​

Benchmarking, the TUI dashboard, runtime profiling, key generation, and metrics testing.

Generated reference

Flag tables below are generated from the CLI and kept in sync by a drift check.

cargoship benchmark ​

Benchmark compression algorithms

Synopsis ​

Benchmark different compression algorithms to find the optimal one for your data.

This command tests various compression algorithms (gzip, zlib, zstd, lz4, s2) with different compression levels to help you choose the best algorithm based on your performance and size requirements.

Examples:

Benchmark with random data ​

cargoship benchmark --size 10MB

Benchmark with specific data type simulation ​

cargoship benchmark --size 50MB --data-type text

Benchmark using a real file ​

cargoship benchmark --file /path/to/data.tar

Output results in JSON format ​

cargoship benchmark --size 1GB --format json

cargoship benchmark [flags]

Options ​

      --data-type string   Type of data to simulate (text, binary, mixed, random) (default "mixed")
      --file string        Use real file instead of generated data
      --format string      Output format (table, json) (default "table")
  -h, --help               help for benchmark
      --size string        Size of test data to generate (e.g., 1MB, 10MB, 1GB) (default "10MB")

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
      --profile                      Enable performance profiling. This will generate profile files in a temp directory
  -t, --trace                        Enable trace messages in output
  -v, --verbose                      Enable verbose output

cargoship dashboard ​

Launch the CargoShip TUI dashboard

Synopsis ​

Launch the CargoShip terminal dashboard — a read-only view over your real data. It fabricates nothing; when a source has no data it says so.

Views (local, always available):

  • 🏠 Overview: this month's recorded spend, budget used, in-progress uploads
  • 💰 Costs: recorded spend this month by storage class, plus budget status
  • 📦 Uploads: in-progress / resumable uploads and their progress

Passing an S3 target adds three bucket-backed views:

  • 🗂️ Inventory: completed uploads, read from the manifests under the prefix
  • 🔎 Analyze: an on-demand bucket cost/savings scan (press 'a'; not automatic)
  • 🚢 Fleet: ghostship writers reporting under the prefix (heartbeat, #615)

Local data comes from the cost ledger (see 'cargoship cost') and upload state (see 'cargoship resume'). To browse and restore archived data, use 'cargoship browse'.

Navigation: Tab / ← → Switch view 1-6 Jump to a view ↑ ↓ Move in a table a Analyze (with an S3 target) R Refresh now Q / Ctrl+C Quit

cargoship dashboard [s3://bucket[/prefix]] [flags]

Examples ​

  cargoship dashboard
  cargoship dashboard --view costs
  cargoship dashboard s3://my-bucket/backups   # adds Inventory + Analyze + Fleet

Options ​

  -h, --help               help for dashboard
      --profile string     AWS profile for the S3 target
      --refresh duration   Data refresh interval (e.g. 5s, 1m; default 5s)
      --region string      AWS region for the S3 target (auto-detected if empty)
      --view string        Initial view (overview, costs, uploads, inventory, analyze, fleet) (default "overview")

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
  -t, --trace                        Enable trace messages in output
  -v, --verbose                      Enable verbose output

cargoship profile ​

Performance profiling and diagnostics tools

Synopsis ​

Performance profiling and diagnostics tools for CargoShip.

This command provides comprehensive profiling capabilities to help diagnose performance issues and optimize CargoShip operations.

Available profile types: • CPU: CPU usage profiling (--cpu) • Memory: Memory allocation profiling (--memory) • Goroutine: Goroutine stack traces (--goroutine) • Block: Blocking operations profiling (--block) • Mutex: Mutex contention profiling (--mutex) • Trace: Execution trace for detailed analysis (--trace) • Allocs: Memory allocation profiling (--allocs)

Examples:

Capture CPU profile for 30 seconds ​

cargoship profile collect --cpu --duration 30

Capture memory profile ​

cargoship profile collect --memory

Capture all profiles ​

cargoship profile collect --cpu --memory --goroutine --duration 60

List available profile files ​

cargoship profile list

Show current runtime statistics ​

cargoship profile stats

Options ​

  -h, --help   help for profile

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
      --profile                      Enable performance profiling. This will generate profile files in a temp directory
  -t, --trace                        Enable trace messages in output
  -v, --verbose                      Enable verbose output

cargoship profile collect ​

Collect performance profiles

Synopsis ​

Collect various performance profiles for analysis.

By default, profiles are saved to a temporary directory. Use --output-dir to specify a custom location.

cargoship profile collect [flags]

Options ​

      --allocs              Collect allocation profile
      --block               Collect blocking operations profile
      --cpu                 Collect CPU profile
  -d, --duration int        Duration in seconds for CPU profiling (default 30)
      --goroutine           Collect goroutine profile
  -h, --help                help for collect
      --memory              Collect memory profile
      --mutex               Collect mutex contention profile
  -o, --output-dir string   Output directory for profile files (default: temp dir)
      --trace               Collect execution trace

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
      --profile                      Enable performance profiling. This will generate profile files in a temp directory
  -v, --verbose                      Enable verbose output

cargoship profile list ​

List available profile files

Synopsis ​

List all profile files in the default profile directory.

cargoship profile list [flags]

Options ​

  -d, --dir string   Directory to list profiles from (default: temp dir)
  -h, --help         help for list

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
      --profile                      Enable performance profiling. This will generate profile files in a temp directory
  -t, --trace                        Enable trace messages in output
  -v, --verbose                      Enable verbose output

cargoship profile stats ​

Show current runtime statistics

Synopsis ​

Show current runtime statistics including memory usage, goroutines, and GC statistics.

cargoship profile stats [flags]

Options ​

  -h, --help   help for stats

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
      --profile                      Enable performance profiling. This will generate profile files in a temp directory
  -t, --trace                        Enable trace messages in output
  -v, --verbose                      Enable verbose output

cargoship create keys ​

Create a new private and public key pair

Synopsis ​

Create a new GPG private and public key pair.

The private key is encrypted with a passphrase. Supply it interactively when prompted, or set CARGOSHIP_GPG_PASSPHRASE for non-interactive use. To generate an unencrypted private key, pass --no-passphrase explicitly.

Keys are written to the current directory unless --destination is given. An existing private.key or public.key is never overwritten.

cargoship create keys [flags]

Options ​

  -b, --bits int        Bit length of the key (default 4096)
  -e, --email string    Email of the key
  -h, --help            help for keys
  -n, --name string     Name of the key
      --no-passphrase   Generate an UNENCRYPTED private key (not recommended; the file is plaintext key material)
      --type KeyType    key type (rsa, x25519) (default rsa)

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
  -d, --destination string           Directory to write files in to. Defaults to the current directory
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
      --profile                      Enable performance profiling. This will generate profile files in a temp directory
  -t, --trace                        Enable trace messages in output
  -v, --verbose                      Enable verbose output

cargoship metrics ​

Test CloudWatch metrics integration

Synopsis ​

Test CloudWatch metrics integration for CargoShip observability.

This command allows you to test the CloudWatch metrics publishing functionality to ensure proper integration with AWS monitoring services.

Examples:

Test metrics publishing ​

cargoship metrics --test

Test with custom namespace and region ​

cargoship metrics --test --namespace "CargoShip/Prod" --region us-east-1

cargoship metrics [flags]

Options ​

  -h, --help               help for metrics
      --namespace string   CloudWatch namespace for metrics (default "CargoShip/Test")
      --region string      AWS region for CloudWatch (default "us-west-2")
      --test               Send test metrics to CloudWatch

Options inherited from parent commands ​

      --allow-public-observability   Permit the pprof/Prometheus endpoints to bind a non-loopback (public) interface; they are unauthenticated, so this exposes them to the network
      --context string               Override execution context (local, repl)
      --memory-limit string          Set a memory limit for the run. This will slow things down, but will less likely to OOM in certain situations. Avoid this unless you are having memory issues.
      --pprof                        Enable runtime profiling HTTP endpoint at localhost:6060
      --pprof-addr string            Address for runtime profiling HTTP endpoint (default "localhost:6060")
      --profile                      Enable performance profiling. This will generate profile files in a temp directory
  -t, --trace                        Enable trace messages in output
  -v, --verbose                      Enable verbose output