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

Appearance

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 ​

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 ​

      --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 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 ​

      --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 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
  • agent: Launch agent monitoring and management
  • 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 agent context
  cargoship context switch agent

  # 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 ​

      --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 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 ​

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

Switch to a different execution context

Synopsis ​

Switch to a different execution context.

Available contexts:

  • local: Local filesystem operations and archive creation
  • agent: Launch agent monitoring and management
  • repl: Interactive shell mode with command discovery
cargoship context switch <context> [flags]

Examples ​

  cargoship context switch local
  cargoship context switch agent
  cargoship context switch repl

Options ​

  -h, --help   help for switch

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 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 ​

      --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 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 ​

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