Configuration & context commands

Manage CargoShip's configuration file, run the setup wizard, and switch execution contexts. Guides: Config files & precedence, Setup wizard, Execution contexts.

Generated reference

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

• cargoship config
  • Synopsis
  • Options
  • Options inherited from parent commands
• cargoship setup
  • Synopsis
  • Options
  • Options inherited from parent commands
• cargoship context
  • Synopsis
  • Examples
  • Options
  • Options inherited from parent commands
• cargoship context list
  • Synopsis
  • Options
  • Options inherited from parent commands
• cargoship context switch
  • Synopsis
  • Examples
  • Options
  • Options inherited from parent commands
• cargoship context show
  • Synopsis
  • Options
  • Options inherited from parent commands
• cargoship context reset
  • Synopsis
  • Options
  • Options inherited from parent commands

cargoship config

Manage CargoShip configuration

Synopsis

Manage CargoShip configuration files and settings.

CargoShip uses YAML configuration files to store settings for AWS, storage, upload optimization, metrics, logging, and security. Configuration can be loaded from multiple sources with the following precedence:

1. Command line flags (highest priority)
2. Environment variables (CARGOSHIP_*)
3. Configuration file
4. Built-in defaults (lowest priority)

Configuration file locations (searched in order):

• ~/.cargoship.yaml
• ~/.config/cargoship/.cargoship.yaml
• ./.cargoship.yaml

Examples:

Generate example configuration file

cargoship config --generate

Show current configuration

cargoship config --show

Validate configuration file

cargoship config --validate --file ~/.cargoship.yaml

Show configuration in JSON format

cargoship config --show --format json

cargoship config [flags]

Options

      --edit                Edit configuration file with default editor
      --file string         Configuration file path
      --format string       Output format (yaml, json) (default "yaml")
      --generate            Generate example configuration file
  -h, --help                help for config
      --show                Show current configuration
      --validate            Validate configuration file
      --validate-detailed   Validate configuration with AWS connectivity and bucket access checks

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 setup

Interactive setup wizard for CargoShip configuration

Synopsis

Interactive setup wizard that guides you through CargoShip configuration.

This wizard will help you: • Configure AWS credentials and region • Verify S3 bucket access • Set optimal upload parameters based on your use case • Test your configuration

The wizard will create a .cargoship.yaml file in your home directory.

Examples:

Run interactive setup

cargoship setup

Save configuration to custom location

cargoship setup --output /path/to/config.yaml

cargoship setup [flags]

Options

  -h, --help              help for setup
      --non-interactive   Run in non-interactive mode with defaults
      --output string     Custom configuration file path (default: ~/.cargoship.yaml)

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 context

Manage CargoShip execution context

Synopsis

Manage CargoShip execution context to control which commands are available.

Context determines the operational mode:

• local: Local filesystem operations and archive creation
• repl: Interactive shell mode with command discovery

The current context is cached in ~/.cargoship-context and persists between sessions.

cargoship context [flags]

Examples

  # Show current context
  cargoship context

  # Switch to repl context
  cargoship context switch repl

  # List available contexts
  cargoship context list

  # Reset to default (local) context
  cargoship context reset

  # Show context with details
  cargoship context show

Options

  -h, --help   help for context

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 context list

List all available execution contexts

Synopsis

List all available execution contexts with descriptions.

cargoship context list [flags]

Options

  -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 context switch

Switch to a different execution context

Synopsis

Switch to a different execution context.

Available contexts:

• local: Local filesystem operations and archive creation
• repl: Interactive shell mode with command discovery

cargoship context switch <context> [flags]

Examples

  cargoship context switch local
  cargoship context switch repl

Options

  -h, --help   help for switch

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 context show

Show detailed context information

Synopsis

Show detailed information about the current context including cached endpoints, working directory, and context file location.

cargoship context show [flags]

Options

  -h, --help   help for show

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 context reset

Reset context to default (local)

Synopsis

Reset the execution context to default (local) and remove the context cache file. This is useful for troubleshooting or starting fresh.

cargoship context reset [flags]

Options

  -h, --help   help for reset

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