Notes for building this CLI from source and working on it. If you just want
to use mapbox, see the README instead.
Needs Rust via rustup. Nothing else — no second repository, no token, no network beyond crates.io:
cargo build --release
./target/release/mapbox --helpcargo build
cargo fmt
cargo clippy --all-targets -- -D warnings
cargo testAll four are a condition of a change landing, and CI runs the same ones.
cargo fmt and cargo clippy before the push rather than after it: the
lints below are denied in Cargo.toml, so a violation is a compile error
and not a style note.
cargo test never sends a request Mapbox reads — it answers to fake tokens
and a fake server, so the suite runs offline and on a machine that has never
logged in.
Four rules the compiler holds rather than a reviewer, declared in
Cargo.toml with the reasoning beside each: no unsafe, no println!
(stdout belongs to output::emit, the single place --output is honored),
no dbg!, no todo!/unimplemented!.
Write American English: comments, documentation, commit messages, and every
string the CLI prints. prose_is_american_english in
tests/source_guards.rs reads the files and fails on the British spelling,
so this is a test rather than something a reviewer has to notice, and the
failure names the file and the line. It leaves two things alone on purpose.
Fenced code blocks, because sample output and captured API responses are
quoted rather than written, and rewriting a word inside one would make the
document misquote its source. And the cancelled error code, which is a
compatibility promise scripts may match on rather than a spelling.
Commands are generated at build time from the OpenAPI specs in openapi/,
which are vendored: src/spec.rs names each one through include_str!, so
a clone compiles without fetching anything.
Those specs are derived rather than written here. They come from Mapbox's
own descriptions of its APIs through a maintainer-only regeneration step, so
an edit to openapi/ is undone by the next sync — and what a Mapbox API
accepts is not something this repository decides in the first place. If a
command is missing a parameter the API supports, or describes one wrongly,
open an issue naming the operation and what it should be; the fix is made
where the specs are maintained, which is inside Mapbox.
custom-openapi/ is the exception, and the one place a spec here is
editable: hand-authored specs for APIs Mapbox publishes no description for.
See its own README.
build.rs records which upstream commit the vendored specs came from, when
that information is available to it. It is best-effort and can never fail a
build — read its header before changing it.
See docs/architecture.md for the trust-boundary and data-flow diagram (OAuth login, credential storage, API requests).
While this is 0.x, a breaking change bumps the minor version
(0.1.5 → 0.2.0); everything else bumps the patch. From 1.0 on, plain
semver. Breaking: a command/flag removed, renamed,
or given a new default; an exit code or stdout/stderr change; a --schema
field removed or repurposed. Not breaking: new commands, new API response
fields, new --schema fields, and any wording.
Deprecated commands and endpoints print a warning before the request goes
out, and are marked [deprecated] in --help and --schema.
Official signed binaries are built and published by Mapbox from a separate, private repository. Nothing about that pipeline is needed to build, test or change the CLI, and nothing here depends on it.