Cost, budget & alerts commands
Estimate spend, analyze existing buckets, track project costs, set budgets, and configure alerts. Guides: Estimating costs, Cost management, Budgets, Alerts, Lifecycle.
Generated reference
Flag tables below are generated from the CLI and kept in sync by a drift check. cargoship budget … and cargoship cost budget … are the same subcommand tree exposed in two places.
cargoship estimate
Estimate AWS costs for archiving data
Synopsis
Estimate the cost of archiving data to AWS S3.
This command analyzes the specified directory and provides detailed cost estimates for different storage classes, including storage, transfer, and request costs.
Examples: cargoship estimate ./research-data cargoship estimate /data --storage-class glacier --format json cargoship estimate . --show-recommendations --region us-west-2
cargoship estimate [path] [flags]Options
--bandwidth float Network bandwidth in MB/s for optimization (0 = auto-detect)
-f, --format string Output format (table, json) (default "table")
-h, --help help for estimate
--max-prefixes int Maximum prefixes for parallel upload analysis (0 = auto)
--real-time-pricing Use real-time AWS pricing (requires AWS credentials)
--region string AWS region for cost calculation (default "us-east-1")
--show-comparison Show cost comparison: naive upload vs CargoShip chunking (Issue #169)
--show-parallel Show parallel upload optimization recommendations (default true)
--show-recommendations Show cost optimization recommendations (default true)
--show-upload-optimization Show intelligent upload sizing recommendations (default true)
-s, --storage-class string Target storage class for estimationOptions 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 outputcargoship analyze
Analyze existing S3 storage and show potential CargoShip savings
Synopsis
Analyze an existing S3 bucket and calculate how much CargoShip could save.
This command scans your existing S3 storage, calculates current costs, and shows potential savings from re-grating to CargoShip's chunked format.
Supports AWS S3 and S3-compatible providers (Wasabi, Backblaze B2, MinIO).
Examples:
AWS S3
cargoship analyze s3://my-bucket cargoship analyze s3://my-bucket/data --show-savings cargoship analyze s3://my-bucket --format json cargoship analyze s3://my-bucket --sampling --sample-size 10000 cargoship analyze s3://my-bucket --region us-west-2
Wasabi
cargoship analyze s3://my-bucket --provider wasabi --endpoint-url https://s3.wasabisys.com
Backblaze B2
cargoship analyze s3://my-bucket --provider b2 --endpoint-url https://s3.us-west-002.backblazeb2.com
MinIO (self-hosted)
cargoship analyze s3://my-bucket --provider minio --endpoint-url https://minio.example.com
cargoship analyze <s3://bucket[/prefix]> [flags]Options
--endpoint-url string S3-compatible endpoint URL (for Wasabi, B2, MinIO, etc.)
-f, --format string Output format (table, json) (default "table")
-h, --help help for analyze
--profile string AWS profile to use
--progress Show progress during bucket scan (default true)
--provider string Storage provider (aws, wasabi, b2, minio, custom) (default "aws")
--region string AWS region (auto-detected from bucket if not specified)
--sample-size int Sample size for quick estimates (when --sampling enabled) (default 10000)
--sampling Use sampling mode for quick estimates on large buckets
--show-savings Show savings comparison with CargoShip re-gration (default true)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")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship lifecycle
Manage S3 lifecycle policies for cost optimization
Synopsis
Manage S3 lifecycle policies to automatically optimize storage costs.
CargoShip provides predefined lifecycle policy templates optimized for different use cases, or you can create custom policies based on your access patterns.
Examples:
List available policy templates
cargoship lifecycle --list-templates
Apply archive optimization policy
cargoship lifecycle --bucket my-bucket --template archive-optimization
Estimate savings for a policy
cargoship lifecycle --bucket my-bucket --template intelligent-tiering --estimate-size 100
Export current policy
cargoship lifecycle --bucket my-bucket --export policy.json
Remove lifecycle policy
cargoship lifecycle --bucket my-bucket --remove
cargoship lifecycle [flags]Options
--bucket string S3 bucket name (required unless listing templates)
--estimate-size float Data size in GB for savings estimation
--export string Export current policy to file
-h, --help help for lifecycle
--import string Import policy from file
--list-templates List available policy templates
--region string AWS region (default "us-east-1")
--remove Remove existing lifecycle policy
--template string Lifecycle policy template to applyOptions 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 outputcargoship cost
Cost management and budget tracking
Synopsis
Cost management and budget tracking for CargoShip uploads.
The cost command provides cost estimation, budget tracking, and pricing information:
- Estimate costs for planned uploads
- View budget status and spending
- Get current AWS pricing for your region
This replaces the standalone 'cargoship-cost' tool with integrated functionality.
Examples:
Estimate cost for uploading 100GB
cargoship cost estimate --size 100GB --region us-west-2
Show budget status
cargoship cost budget
Get current pricing
cargoship cost pricing --region us-west-2
Generate cost report
cargoship cost report --period month
cargoship cost [flags]Options
-h, --help help for cost
--json Output as JSON
-r, --region string AWS region (default "us-west-2")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 outputcargoship cost estimate
Estimate cost for a planned upload
Synopsis
Estimate storage costs before uploading.
Calculates monthly storage costs based on:
- Data size (uncompressed)
- Storage class (STANDARD, INTELLIGENT_TIERING, GLACIER, etc.)
- Region-specific pricing
Examples:
Estimate cost for 100GB upload
cargoship cost estimate --size 100GB
Estimate with specific storage class
cargoship cost estimate --size 500GB --storage-class GLACIER
Estimate for different region
cargoship cost estimate --size 1TB --region eu-west-1
cargoship cost estimate [flags]Options
-h, --help help for estimate
--operation string Operation type (upload, download) (default "upload")
--size string Data size (e.g., 100GB, 500MB, 1TB) (required)
--storage-class string Storage class (STANDARD, STANDARD_IA, GLACIER, etc.) (default "STANDARD")Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost upload
Show actual cost for a specific upload
Synopsis
Display actual storage costs for a CargoShip upload.
Query the manifest to calculate real costs based on:
- Actual compressed size stored in S3
- Storage duration (from CreatedAt timestamp)
- Region and storage class
- Compression savings achieved
Examples:
Show cost for specific upload
cargoship cost upload --bucket my-bucket --upload-id 20231208-123456-abcd1234
Show cost with compression ROI details
cargoship cost upload --bucket my-bucket --upload-id xxx --show-savings
JSON output
cargoship cost upload --bucket my-bucket --upload-id xxx --json
cargoship cost upload [flags]Options
--bucket string S3 bucket name (required)
-h, --help help for upload
--prefix string S3 prefix (default "cargoship")
--show-savings Show compression savings (default true)
--upload-id string Upload ID (required)Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost pricing
Show current AWS pricing
Synopsis
Display current AWS S3 pricing for your region.
Shows pricing for:
- Storage (per GB per month) for all storage classes
- Request costs (PUT, GET, etc.)
- Data transfer costs
Examples:
Show pricing for default region
cargoship cost pricing
Show pricing for specific region
cargoship cost pricing --region eu-west-1
Pricing as JSON
cargoship cost pricing --json
cargoship cost pricing [flags]Options
-h, --help help for pricingOptions inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost report
Generate cost report
Synopsis
Generate detailed cost report for a time period or compliance report.
Standard mode (default): Shows total costs, breakdown by service/region, trends, and recommendations.
Compliance mode (--format compliance): Generates an NSF or NIH data-management compliance report for a specific budget/project, including data provenance, reproducibility info, and DMP.
Examples:
Monthly report
cargoship cost report --period month
Export report to file
cargoship cost report --period month --output report.json
NSF compliance report
cargoship cost report --budget my-project-id --grant NSF-2024-12345 --format compliance
NIH compliance report (text)
cargoship cost report --budget my-project-id --grant R01-GM123456 --format compliance --agency NIH --text
cargoship cost report [flags]Options
--agency string Funding agency for compliance report (NSF or NIH) (default "NSF")
--budget string Budget/project ID for compliance report
--format string Output format: compliance (enables compliance report mode)
--grant string Grant/award number (e.g., NSF-2024-12345, R01-GM123456)
-h, --help help for report
--output string Output file path (default: stdout)
--period string Report period (today, week, month, last_month) (default "month")
--text Render compliance report as human-readable text (default: JSON)Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost projects
List all projects with cost records
Synopsis
List all projects (manifest upload IDs) that have associated cost records.
Projects are identified by their manifest upload IDs (e.g., 20251206-abc123). Each upload to S3 creates a unique project that can be tracked separately.
Examples:
List all projects
cargoship cost projects
List projects as JSON
cargoship cost projects --json
cargoship cost projects [flags]Options
-h, --help help for projectsOptions inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost project
Show costs for a specific project
Synopsis
Show detailed cost information for a specific project (manifest upload ID).
Displays:
- Total costs and savings for the project
- Total files and data size uploaded
- Cost breakdown by region and storage class
- First and last upload timestamps
- Average cost per GB
Examples:
Show costs for specific project
cargoship cost project 20251206-abc123
Show project costs for specific period
cargoship cost project 20251206-abc123 --period month
Project costs as JSON
cargoship cost project 20251206-abc123 --json
cargoship cost project PROJECT_ID [flags]Options
-h, --help help for project
--period string Report period (all, today, week, month, last_month) (default "all")Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost forecast
Generate cost forecasts with ML-based projections
Synopsis
Generate cost forecasts using multiple forecasting models.
Predicts future costs based on historical spending patterns using:
- Linear regression (best for stable/trending patterns)
- Exponential smoothing (for seasonal patterns)
- Moving average (for smoothing volatility)
- Ensemble model (combines all models)
Displays:
- Predicted costs at 7, 14, 30, 60, 90 days
- Confidence intervals (90%, 95%, 99%)
- Model accuracy metrics (R², MAE, RMSE)
- Daily cost forecasts
Examples:
Generate forecast for all projects (global)
cargoship cost forecast
Generate forecast for specific project
cargoship cost forecast 20251206-abc123
Forecast with specific model
cargoship cost forecast --model linear
Forecast as JSON
cargoship cost forecast --json
cargoship cost forecast [PROJECT_ID] [flags]Options
--days int Number of days to forecast (7-90) (default 90)
-h, --help help for forecast
--model string Forecasting model (linear, exponential, moving_average, ensemble) (default "linear")Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost burnrate
Analyze burn rate with trend detection
Synopsis
Analyze current and historical burn rates with trend detection.
Provides detailed burn rate metrics:
- Current rates (daily, weekly, monthly)
- Historical statistics (average, min, max, std dev, volatility)
- Trend detection (increasing/decreasing/stable) with strength
- Acceleration rate (change in burn rate per day)
- Predicted future burn rates (30/60/90 days)
- Confidence intervals for predictions
Examples:
Analyze burn rate for all projects (global)
cargoship cost burnrate
Analyze burn rate for specific project
cargoship cost burnrate 20251206-abc123
Analyze last 60 days
cargoship cost burnrate --days 60
Burn rate as JSON
cargoship cost burnrate --json
cargoship cost burnrate [PROJECT_ID] [flags]Options
--days int Number of days of historical data to analyze (7-365) (default 90)
-h, --help help for burnrateOptions inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost exhaustion
Predict when budget will be exhausted
Synopsis
Predict when a budget will be exhausted based on current spending patterns.
Calculates:
- Exact date when budget will run out
- Days until exhaustion
- Probability of exhaustion (based on confidence intervals)
- Budget usage forecast with confidence bounds
Handles edge cases:
- Budget already exhausted (today)
- Budget never exhausts within 90 days
- High/low confidence scenarios
Examples:
Predict exhaustion for $1000 budget (global)
cargoship cost exhaustion --budget 1000
Predict for specific project
cargoship cost exhaustion 20251206-abc123 --budget 500
Include current spending
cargoship cost exhaustion --budget 1000 --spent 400
Exhaustion prediction as JSON
cargoship cost exhaustion --budget 1000 --json
cargoship cost exhaustion [PROJECT_ID] --budget AMOUNT [flags]Options
--budget float Total budget amount (required)
-h, --help help for exhaustion
--spent float Amount already spent (default: calculated from cost records)Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost benchmark-compare
Compare CargoShip costs vs competitors for benchmarking
Synopsis
Calculate and compare costs for benchmark scenarios.
Shows CargoShip's cost advantages:
- Compression savings (20-70% data reduction)
- Intelligent chunking (50% fewer requests)
- Storage tier optimization (30-60% cost reduction)
- Deduplication (variable savings)
Output format is JSON for easy integration with benchmark scripts.
Examples:
Compare CargoShip (3:1 compression) vs competitor (no compression)
cargoship cost benchmark-compare --size 100GB --files 10000
--compression-ratio 3.0 --storage-class GLACIER
Compare with deduplication
cargoship cost benchmark-compare --size 100GB --files 10000
--compression-ratio 2.0 --dedup-ratio 2.0
Competitor cost only
cargoship cost benchmark-compare --tool s5cmd --size 100GB --files 10000
cargoship cost benchmark-compare [flags]Options
--chart Display ASCII cost comparison charts
--compression-ratio float Compression ratio (e.g., 3.0 for 3:1) (default 1)
--dedup-ratio float Deduplication ratio (e.g., 2.0 for 2:1) (default 1)
--files int Number of files (required)
-h, --help help for benchmark-compare
--size-gb float Data size in GB (required)
--storage-class string Storage class (default "STANDARD")
--tool string Tool name (s5cmd, rclone, aws-cli, cargoship)Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost summary
Summarize costs by DVC stage or git commit
Synopsis
Aggregate recorded costs by DVC pipeline stage or git commit.
Requires cost records that were tagged with DVC provenance information (populated automatically when --dvc-stage is passed to 'cargoship upload').
Examples:
Summarise costs for a specific DVC stage
cargoship cost summary --by-dvc-stage preprocess
List all records for a git commit
cargoship cost summary --git-commit abc1234
cargoship cost summary [flags]Options
--by-dvc-stage string Aggregate costs for this DVC pipeline stage
--git-commit string List costs tagged with this git commit SHA
-h, --help help for summaryOptions inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship cost history
Show the recorded per-upload outcome history
Synopsis
Display the durable per-upload outcome history (metadata only).
This history is opt-in and OFF by default. Enable it with the CARGOSHIP_UPLOAD_HISTORY environment variable (1, true, or a file path) or the cost_control.upload_history_location config key. Each successful upload then appends a metadata-only record — dataset shape, chosen parameters, and measured outcomes (compression ratio, throughput, cost). No file content, names, or paths are recorded.
Examples:
Show the recorded history
cargoship cost history
As JSON, most recent first
cargoship cost history --json
cargoship cost history [flags]Options
-h, --help help for history
--limit int Maximum number of records to show (0 = all) (default 20)Options inherited from parent commands
--context string Override execution context (local, agent, repl)
--json Output as JSON
--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
-r, --region string AWS region (default "us-west-2")
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship budget
Manage project budgets and volume quotas
Synopsis
Manage project-specific budgets and volume quotas.
Project budgets allow you to set cost and volume limits per project (manifest upload). This enables granular cost control where operations can be blocked if they would exceed EITHER cost budgets OR volume quotas.
Features:
- Set cost budgets per project (e.g., $1000/month)
- Set volume quotas per project (e.g., 500GB/month)
- Separate alert thresholds for cost vs volume
- Hierarchical enforcement (project limits, then global limits)
- Real-time budget status with burn rate tracking
Examples:
Show budget status for a project
cargoship budget status project1
Set project budget (cost only)
cargoship budget set project1 --cost 1000
Set project with both cost and volume limits
cargoship budget set project1 --cost 1000 --volume 500
Set project with custom alert thresholds
cargoship budget set project1 --cost 1000 --volume 500 --cost-alert 0.85 --volume-alert 0.75
List all project budgets
cargoship budget list
Remove project budget
cargoship budget remove project1
cargoship budget [flags]Options
-h, --help help for budget
--store string Budget store location: local (default) or s3://bucket/prefix for a shared, durable storeOptions 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 outputcargoship budget status
Show budget status for a project
Synopsis
Display detailed budget status for a specific project.
Shows:
- Maximum cost budget and current spending
- Maximum volume quota and current usage
- Remaining budget/quota
- Usage percentages
- Daily burn rates
- Projected end-of-period usage
- Alert status
Examples:
Show budget status
cargoship budget status project1
Status as JSON
cargoship budget status project1 --json
Show the org/team-wide budget status
cargoship budget status --global
cargoship budget status <project-id> [flags]Options
--global Show the org/team-wide budget status instead of a project's
-h, --help help for status
--json Output as JSONOptions 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
--store string Budget store location: local (default) or s3://bucket/prefix for a shared, durable store
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship budget set
Set budget and quota for a project
Synopsis
Set cost budget and/or volume quota for a specific project.
Budget values:
- Cost budget in USD (e.g., 1000 = $1000)
- Volume quota in GB (e.g., 500 = 500GB)
- Alert thresholds as percentages (0.0-1.0, e.g., 0.8 = 80%)
- Use 0 for unlimited
Examples:
Set cost budget only
cargoship budget set project1 --cost 1000
Set volume quota only
cargoship budget set project1 --volume 500
Set both cost and volume limits
cargoship budget set project1 --cost 1000 --volume 500
Set with custom alert thresholds
cargoship budget set project1 --cost 1000 --volume 500 \ --cost-alert 0.85 --volume-alert 0.75
Set unlimited
cargoship budget set project1 --cost 0 --volume 0
Set the org/team-wide budget ceiling (across all projects)
cargoship budget set --global --cost 10000 --volume 5000
cargoship budget set <project-id> [flags]Options
--cost float Maximum cost budget in USD (0 = unlimited)
--cost-alert float Cost alert threshold (0.0-1.0, default 0.8) (default 0.8)
--global Set the org/team-wide budget ceiling (across all projects) instead of a per-project budget
-h, --help help for set
--volume float Maximum volume quota in GB (0 = unlimited)
--volume-alert float Volume alert threshold (0.0-1.0, default 0.75) (default 0.75)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
--store string Budget store location: local (default) or s3://bucket/prefix for a shared, durable store
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship budget list
List all project budgets
Synopsis
List all configured project budgets and their current status.
Shows for each project:
- Project ID
- Cost budget and current spending
- Volume quota and current usage
- Alert status
Examples:
List all project budgets
cargoship budget list
List as JSON
cargoship budget list --json
cargoship budget list [flags]Options
-h, --help help for list
--json Output as JSONOptions 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
--store string Budget store location: local (default) or s3://bucket/prefix for a shared, durable store
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship budget remove
Remove budget for a project
Synopsis
Remove cost budget and volume quota for a specific project.
After removal, the project will use the global budget and quota settings.
Examples:
Remove project budget
cargoship budget remove project1
cargoship budget remove <project-id> [flags]Options
-h, --help help for removeOptions 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
--store string Budget store location: local (default) or s3://bucket/prefix for a shared, durable store
-t, --trace Enable trace messages in output
-v, --verbose Enable verbose outputcargoship alerts
Manage budget alert notifications
Synopsis
Configure and test budget alert notifications.
Budget alerts support multiple notification channels:
- Webhooks (HTTP POST with JSON payload)
- CloudWatch (AWS CloudWatch metrics and alarms)
- Email (SMTP with TLS encryption)
- Slack (webhook integration with rich formatting)
Features:
- Configure multiple notification channels
- Test alert delivery before enabling
- View current alert configuration
- Enable/disable specific channels
Examples:
Show current alert configuration
cargoship alerts config
Configure email notifications
cargoship alerts configure email \ --smtp-host smtp.gmail.com \ --smtp-port 587 \ --smtp-username alerts@example.com \ --smtp-password "app-password" \ --smtp-from "cargoship@example.com" \ --recipients admin@example.com,ops@example.com
Configure Slack notifications
cargoship alerts configure slack \ --webhook-url "https://hooks.slack.com/services/T00/B00/abc123" \ --channel "#cargoship-alerts" \ --username "CargoShip Monitor"
Test alert delivery
cargoship alerts test
Enable/disable specific channels
cargoship alerts enable email cargoship alerts disable slack
cargoship alerts [flags]Options
-h, --help help for alertsOptions 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 outputcargoship alerts config
Show current alert configuration
Synopsis
Display the current alert notification configuration.
Shows:
- Enabled notification channels
- Channel-specific configuration
- Alert thresholds and cooldown periods
- Last alert timestamps
Examples:
Show configuration
cargoship alerts config
Show as JSON
cargoship alerts config --json
cargoship alerts config [flags]Options
-h, --help help for config
--json Output as JSONOptions 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 outputcargoship alerts configure
Configure alert notification channels
Synopsis
Configure specific alert notification channels.
Supported channels:
- email: SMTP email notifications with TLS
- slack: Slack webhook notifications
- webhook: Custom HTTP webhook
- cloudwatch: AWS CloudWatch integration
Examples:
Configure email
cargoship alerts configure email \ --smtp-host smtp.gmail.com \ --smtp-port 587 \ --smtp-username alerts@example.com \ --smtp-password "app-password" \ --smtp-from "cargoship@example.com" \ --recipients admin@example.com,ops@example.com
Configure Slack
cargoship alerts configure slack \ --webhook-url "https://hooks.slack.com/services/..." \ --channel "#cargoship-alerts"
cargoship alerts configure [channel] [flags]Options
--channel string Slack channel (e.g., #cargoship-alerts)
-h, --help help for configure
--namespace string CloudWatch namespace (default "CargoShip/Budget")
--recipients strings Email recipients (comma-separated)
--smtp-from string From email address
--smtp-host string SMTP server hostname
--smtp-password string SMTP password
--smtp-port int SMTP server port (default 587)
--smtp-use-tls Use TLS encryption (default true)
--smtp-username string SMTP username
--username string Slack bot username (default "CargoShip Monitor")
--webhook-url string Slack webhook URLOptions 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 outputcargoship alerts test
Test alert notification delivery
Synopsis
Send a test alert to verify notification configuration.
Tests all enabled channels or a specific channel if specified. The test alert uses sample budget data to demonstrate formatting.
Examples:
Test all enabled channels
cargoship alerts test
Test specific channel
cargoship alerts test --channel email
Test with specific severity
cargoship alerts test --severity critical
cargoship alerts test [flags]Options
--channel string Test specific channel (email, slack, webhook, cloudwatch)
-h, --help help for test
--severity string Alert severity (info, warning, critical) (default "warning")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 outputcargoship alerts enable
Enable alert notification channel
Synopsis
Enable a specific alert notification channel.
Supported channels:
- slack
- webhook
- cloudwatch
Examples:
Enable email notifications
cargoship alerts enable email
Enable Slack notifications
cargoship alerts enable slack
cargoship alerts enable [channel] [flags]Options
-h, --help help for enableOptions 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 outputcargoship alerts disable
Disable alert notification channel
Synopsis
Disable a specific alert notification channel.
Supported channels:
- slack
- webhook
- cloudwatch
Examples:
Disable email notifications
cargoship alerts disable email
Disable Slack notifications
cargoship alerts disable slack
cargoship alerts disable [channel] [flags]Options
-h, --help help for disableOptions 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