CLI Documentation

Complete reference for the ballistics-engine command line interface

Installation

Using Cargo (Recommended)

cargo install ballistics-engine

From Source

git clone https://github.com/ajokela/ballistics-engine
cd ballistics-engine
cargo build --release
# Binary at ./target/release/ballistics

With Online Features

Enable API integration and BC table auto-download:

cargo install ballistics-engine --features online

Quick Start

Calculate a basic trajectory for a .308 Winchester:

ballistics trajectory \
  --velocity 2800 \
  --bc 0.462 \
  --mass 168 \
  --diameter 0.308 \
  --drag-model g1 \
  --max-range 1000 \
  --auto-zero 100

Commands

trajectory

Calculate a single ballistic trajectory with full physics modeling.

ballistics trajectory [OPTIONS]

Required Parameters

Option	Description
`-v, --velocity`	Muzzle velocity (fps or m/s)
`-b, --bc`	Ballistic coefficient
`-m, --mass`	Bullet mass (grains or grams)
`-d, --diameter`	Bullet diameter (inches or mm)

Common Options

Option	Default	Description
`--drag-model`	g1	Drag model (g1, g7)
`--max-range`	1000	Maximum range (yards or meters)
`--auto-zero`	-	Zero distance (overrides --angle)
`--sight-height`	1.5"	Scope height above bore
`-o, --output`	table	Output format (table, json, csv)
`--units`	imperial	Unit system (imperial, metric)

Environmental Conditions

Option	Default	Description
`--temperature`	59°F	Air temperature
`--pressure`	29.92 inHg	Barometric pressure
`--humidity`	50%	Relative humidity
`--altitude`	0 ft	Altitude above sea level
`--wind-speed`	0 mph	Wind speed
`--wind-direction`	0°	Wind from (0=N, 90=E)

Advanced Physics

Option	Description
`--enable-spin-drift`	Calculate gyroscopic drift
`--enable-coriolis`	Account for Earth's rotation
`--enable-magnus`	Include Magnus effect
`--enable-wind-shear`	Altitude-dependent wind
`--twist-rate`	Barrel twist (inches/turn)
`--latitude`	Shooter latitude (required for Coriolis)
`--longitude`	Shooter longitude (required for Coriolis)

monte-carlo

Run Monte Carlo simulations to analyze shot dispersion and hit probability.

ballistics monte-carlo [OPTIONS]

Option	Default	Description
`-v, --velocity`	required	Base velocity (m/s)
`-b, --bc`	required	Ballistic coefficient
`-m, --mass`	required	Mass (kg)
`-d, --diameter`	required	Diameter (m)
`-n, --num-sims`	1000	Number of simulations
`--velocity-std`	1.0	Velocity std dev (m/s)
`--angle-std`	0.1	Angle std dev (degrees)
`--bc-std`	0.01	BC std dev
`--wind-std`	1.0	Wind std dev (m/s)
`--target-distance`	-	Distance for hit probability
`-o, --output`	summary	Output (summary, full, statistics)

zero

Calculate the barrel angle needed to zero at a specific distance.

ballistics zero [OPTIONS]

Option	Description
`-v, --velocity`	Muzzle velocity
`-b, --bc`	Ballistic coefficient
`-m, --mass`	Bullet mass
`-d, --diameter`	Bullet diameter
`--target-distance`	Zero distance
`--target-height`	Target height offset (default: 0)
`--sight-height`	Scope height above bore

estimate-bc

Estimate ballistic coefficient from observed trajectory data (two-point method).

ballistics estimate-bc [OPTIONS]

Option	Description
`-v, --velocity`	Initial velocity (m/s)
`-m, --mass`	Mass (kg)
`-d, --diameter`	Diameter (m)
`--distance1`	First measurement distance (m)
`--drop1`	Drop at distance1 (m)
`--distance2`	Second measurement distance (m)
`--drop2`	Drop at distance2 (m)

generate-bc-segments

Generate velocity-dependent BC segments for improved long-range accuracy.

ballistics generate-bc-segments [OPTIONS]

Option	Description
`-b, --bc`	Base ballistic coefficient
`-m, --mass`	Mass (kg)
`-d, --diameter`	Diameter (m)
`--model`	Bullet model (SMK, ELD-M, VLD, etc.)
`--drag-model`	Base drag model (G1, G7)

true-velocity

Calculate effective muzzle velocity from observed drop data. Works in both online and offline modes. Use --offline for fully local calculation, or omit for API-based calculation (requires online feature).

ballistics true-velocity [OPTIONS]

Required Parameters

Option	Description
`--measured-drop`	Measured drop in MILs at the target range
`--range`	Range at which drop was measured
`-b, --bc`	Ballistic coefficient
`-m, --mass`	Bullet weight (grains)
`-d, --diameter`	Bullet diameter/caliber (inches)

Optional Parameters

Option	Default	Description
`--drag-model`	g1	Drag model (g1, g7)
`--chrono-velocity`	-	Chronograph velocity for comparison
`--zero-range`	100	Zero distance (yards)
`--sight-height`	2.0	Sight height above bore (inches)
`--bullet-length`	auto	Bullet length (inches) for BC5D lookup
`--temperature`	59	Temperature (°F)
`--pressure`	29.92	Barometric pressure (inHg)
`--humidity`	50	Humidity (%)
`--altitude`	0	Altitude (feet)

Mode Parameters

Option	Default	Description
`--offline`	false	Force offline mode (local calculation)
`--offline-fallback`	false	Try API first, fall back to local if fails
`--bc-table-dir`	-	Directory with BC5D tables for improved accuracy
`--bc-table-auto`	false	Auto-download BC5D tables (requires online feature)

Examples

# Offline calculation (no network required)
ballistics true-velocity \
  --measured-drop 5.1 \
  --range 600 \
  --bc 0.27 \
  --drag-model g7 \
  --mass 140 \
  --diameter 0.264 \
  --offline

# With chronograph comparison
ballistics true-velocity \
  --measured-drop 5.1 \
  --range 600 \
  --bc 0.27 \
  --drag-model g7 \
  --mass 140 \
  --diameter 0.264 \
  --chrono-velocity 2822 \
  --offline

# With BC5D tables for improved accuracy
ballistics true-velocity \
  --measured-drop 5.1 \
  --range 600 \
  --bc 0.27 \
  --drag-model g7 \
  --mass 140 \
  --diameter 0.264 \
  --bc-table-auto \
  --offline

Output shows the effective muzzle velocity that produces the measured drop, the adjustment from your chronograph reading (if provided), confidence level, and convergence details.

Unit Systems

The CLI supports both imperial and metric units. Use --units metric or --units imperial (default).

Measurement	Imperial	Metric
Velocity	fps (feet/sec)	m/s
Mass	grains	grams
Distance	yards	meters
Diameter	inches	millimeters
Temperature	Fahrenheit	Celsius
Pressure	inHg	hPa
Altitude	feet	meters
Wind	mph	m/s

Profiles

Save common configurations in CSV files for quick loading.

Gun Profile (gun_profiles.csv)

name,velocity,bc,mass,diameter,drag_model,twist_rate,sight_height
R700_65CM,2750,0.271,140,0.264,g7,8,1.6
AR15_223,3200,0.243,77,0.224,g7,7,2.6
M1A_308,2650,0.462,168,0.308,g1,12,1.5

Location Profile (locations.csv)

name,altitude,temperature,pressure,humidity,latitude,longitude
HOME_RANGE,500,72,29.85,45,45.5,-122.6
HIGH_DESERT,4500,85,26.5,15,35.2,-106.7
ALASKA,200,35,30.1,60,61.2,-149.9

Using Profiles

# Load gun profile
ballistics trajectory --profile gun_profiles.csv --profile-row R700_65CM --max-range 1000

# Load both gun and location profiles
ballistics trajectory \
  --profile gun_profiles.csv --profile-row R700_65CM \
  --location locations.csv --site HIGH_DESERT \
  --max-range 1500

BC Tables

BC5D tables provide velocity-dependent BC corrections for improved accuracy, especially in transonic regions.

Note: BC5D tables require the online feature for auto-download, or can be used offline with local files.

Auto-Download (Online Feature)

# Auto-download BC5D table for your caliber
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --drag-model g7 --max-range 1500 \
  --bc-table-auto

Local BC5D Tables

# Use locally stored BC5D tables
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --drag-model g7 --max-range 1500 \
  --bc-table-dir ~/.ballistics/bc5d/

Available Calibers

BC5D tables are available for: .224, .243, .264, .277, .284, .308, .338

Advanced Features

Spin Drift

ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --twist-rate 8 --twist-right true \
  --enable-spin-drift \
  --max-range 1000

Coriolis Effect

ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --latitude 45.5 --longitude -122.6 --shot-direction 90 \
  --enable-coriolis \
  --max-range 1500

Uphill/Downhill Shooting

# Shooting uphill at 15 degrees
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --shooting-angle 15 \
  --max-range 800

Powder Temperature Sensitivity

ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --use-powder-sensitivity \
  --powder-temp-sensitivity 1.5 \
  --powder-temp 95 \
  --temperature 95

Online Mode

With the online feature enabled, calculations can be routed through the API for ML-enhanced corrections.

# Use online API for trajectory
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --online \
  --max-range 1500

# Compare local vs API results
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --compare \
  --max-range 1000

# Use online with fallback to local if API unavailable
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --online --offline-fallback \
  --max-range 1000

Online Weather

Fetch real-time weather conditions for your location instead of manually entering temperature, pressure, and humidity. Requires latitude and longitude coordinates.

# Fetch current weather for your location
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --latitude 45.5 --longitude -122.6 \
  --online-weather \
  --max-range 1000

# Combine online weather with Coriolis correction
ballistics trajectory \
  --velocity 2750 --bc 0.271 --mass 140 --diameter 0.264 \
  --latitude 45.5 --longitude -122.6 \
  --online-weather \
  --enable-coriolis --shot-direction 90 \
  --max-range 1500

Tip: When using --online-weather, the API fetches current temperature, barometric pressure, humidity, and density altitude for the specified coordinates. Any manually specified weather parameters will be overridden.

Output Formats

Table (Default)

ballistics trajectory ... -o table

Range    Drop     Drift    Velocity  Energy    Time
(yd)     (in)     (in)     (fps)     (ft-lb)   (s)
────────────────────────────────────────────────────
0        -1.50    0.00     2750      2351      0.000
100      0.00     0.12     2583      2074      0.113
200      -3.42    0.49     2421      1822      0.232
...

CSV

ballistics trajectory ... -o csv

range_yd,drop_in,drift_in,velocity_fps,energy_ftlb,time_s
0,-1.50,0.00,2750,2351,0.000
100,0.00,0.12,2583,2074,0.113
...

JSON

ballistics trajectory ... -o json

{
  "trajectory": [
    {"range": 0, "drop": -1.50, "drift": 0.0, "velocity": 2750, ...},
    ...
  ],
  "summary": {
    "max_range": 1000,
    "zero_range": 100,
    ...
  }
}

Complete Examples

6.5 Creedmoor at 1000 Yards

ballistics trajectory \
  --velocity 2750 \
  --bc 0.271 \
  --mass 140 \
  --diameter 0.264 \
  --drag-model g7 \
  --max-range 1000 \
  --auto-zero 100 \
  --sight-height 1.6 \
  --twist-rate 8 \
  --enable-spin-drift \
  --temperature 72 \
  --altitude 500 \
  --wind-speed 10 \
  --wind-direction 90 \
  -o table

.308 Winchester Long Range

ballistics trajectory \
  --velocity 2650 \
  --bc 0.462 \
  --mass 175 \
  --diameter 0.308 \
  --drag-model g1 \
  --max-range 1200 \
  --auto-zero 100 \
  --altitude 4000 \
  --temperature 55 \
  --pressure 26.5 \
  --enable-spin-drift \
  --twist-rate 10 \
  --bc-table-auto

Monte Carlo Hit Probability

ballistics monte-carlo \
  --velocity 838 \
  --bc 0.271 \
  --mass 0.00907 \
  --diameter 0.00671 \
  --num-sims 10000 \
  --velocity-std 3.0 \
  --angle-std 0.05 \
  --wind-speed 4.5 \
  --wind-std 2.0 \
  --target-distance 914 \
  -o statistics

BC Estimation from Field Data

ballistics estimate-bc \
  --velocity 838 \
  --mass 0.00907 \
  --diameter 0.00671 \
  --distance1 300 \
  --drop1 0.45 \
  --distance2 600 \
  --drop2 2.1