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 ​

      --context string        Override execution context (local, agent, 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 comprehensive CargoShip TUI dashboard

Synopsis ​

Launch the comprehensive CargoShip terminal user interface dashboard.

The TUI provides a full-featured interface with multiple views:

  • 🏠 Overview: System status, storage usage, and quick stats
  • 📦 Archive: Data archival operations, cost estimates, and survey results
  • 📋 Inventory: Browse archived data, search, and restore operations
  • 💰 Costs: Cost analysis, optimization suggestions, and budget tracking
  • 🤖 Agents: Launch agent management and monitoring (when available)
  • ⚙️ Config: Configuration management and profiles
  • 📝 Logs: System logs and monitoring (coming soon)

Navigation: Tab/→ ← - Switch between dashboard views 1-7 - Quick jump to specific view ↑↓ - Focus different sections within view Enter - Select/activate focused item R - Force refresh data Q/Ctrl+C - Exit dashboard

The dashboard adapts based on your current context and available features.

cargoship dashboard [flags]

Examples ​

  # Launch dashboard with overview
  cargoship dashboard

  # Launch with specific view
  cargoship dashboard --view archive
  cargoship dashboard --view costs

  # Launch with agent context
  cargoship --context=agent dashboard

Options ​

  -h, --help               help for dashboard
      --mock-data          Use mock data for testing (development only)
      --refresh duration   Override refresh interval (e.g., 5s, 1m)
      --view string        Initial dashboard view (overview, archive, inventory, costs, agents, config, logs) (default "overview")

Options inherited from parent commands ​

      --context string        Override execution context (local, agent, 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 ​

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 ​

      --context string        Override execution context (local, agent, 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 ​

      --context string        Override execution context (local, agent, 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 ​

      --context string        Override execution context (local, agent, 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 ​

      --context string        Override execution context (local, agent, 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 ​

      --context string        Override execution context (local, agent, 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 ​

      --context string        Override execution context (local, agent, 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