Skip to content
CLI for interacting with the Mapbox Tilesets API
Branch: master
Clone or download
dnomadb Merge pull request #29 from mapbox/install-fixes
handing non json response + requirements in setup
Latest commit 5c07070 Oct 9, 2019


Build Status codecov

CLI for interacting with and preparing data for Mapbox Tilesets API.

Contributing includes information about release processes & running tests. 🙌


# clone
git clone
cd tilesets-cli

# virtual env (optional)
mkvirtualenv tilesets-cli

# install deps
pip install .

# confirm installation was successful
tilesets --help
tilesets --version


Mapbox Access Tokens

In order to use the tilesets endpoints, you need a Mapbox Access Token with tilesets:write and tilesets:read scopes. This is a secret token, so do not share it publicly!

You can either pass the Mapbox access token to each command with the --token flag or export it as an environment variable. Acceptable values are:

  • MapboxAccessToken

Set the environment variable with export

export MAPBOX_ACCESS_TOKEN=my.token



tilesets add-source <username> <id> <file>


  • --no-validation [optional]: do not validate source data locally before uploading


# single file
tilesets add-source <username> <id> ./file.geojson

# multiple files
tilesets add-source <username> <id> file-1.geojson file-4.geojson

# directory of files
tilesets add-source <username> <id> ./path/to/multiple/files/

Reading from a directory will not distinguish between GeoJSON files and non GeoJSON files. All source files will be run through our validator unless you pass the --no-validation flag.


tilesets validate-source <path>

Validates a line delimited GeoJSON source file locally. Example error output:

Invalid line delimited geojson.


tilesets view-source <username> <id>

Get information for a tileset source, such as number of files, the size in bytes, and the ID in mapbox:// protocol format.


tilesets list-sources <username>

List all tileset sources from a particular account. Response is an array of sources.


tilesets delete-source

Permanently delete a tileset source and all of its files. This is not a recoverable action!


Prints the Recipe JSON to stdout.

tilesets view-recipe <tileset_id>


Validates a Recipe JSON document.

tilesets validate-recipe /path/to/recipe.json

Example recipe.json:

  "version": 1,
  "layers": {
    "trees": {
      "source": "mapbox://tileset-source/{username}/trees-data",
      "minzoom": 4,
      "maxzoom": 8

See more details about the recipe spec here. See recipe examples here.

Example error output:

  "errors": [
    "Unknown top-level key \"potato\"."
  "valid": false


Update the Recipe JSON for a tileset. Performs a server-side validation of the new document.

tilesets update-recipe <tileset_id> /path/to/recipe.json


Creates a brand new, empty tileset with a recipe passed in from your local filesystem.

tilesets create <tileset_id> --recipe /path/to/recipe.json --name "My neat tileset"


  • --recipe or -r [required]: path to your Recipe JSON document
  • --name or -n [required]: human-readable name of your tileset. (If your tileset_id is user.my_amazing_tileset, you might want your name field to be "My Amazing Tileset".)
  • --description or -d: description of your tileset
  • --privacy or -p: Set the privacy of the tileset. Allowed values are private and public. If not provided, will default to your plan level on Pay-As-You-Go plans only support public maps.


Queues a tiling job using the recipe provided. Use to publish a new tileset or update an existing one. Returns a job ID for progress tracking.

tilesets publish <tileset_id>


View the status of a tileset. This includes how many jobs are queued, processing, and complete.

tilesets status <tileset_id>


Retrieve a single job for a tileset.

tilesets job <tileset_id> <job_id>

What is a job? Each time you generate or regenerate your output tileset via the publish command (whether that's a new recipe or new source data), a single job is created that processes your data. A tileset can have many jobs, each with a unique identifier. When you publish a tileset, the HTTP response includes the unique job identifier that corresponds to the most recent job. To read more about HTTP design, see this documentation.


Check all jobs associated with a tileset. You can filter jobs by a particular stage - processing, queued, success, or failed.

tilesets jobs <tileset_id> --stage=processing
  • --stage: Filter by the stage of jobs. (Optional.)


List all tilesets for an account. Just lists tileset IDs by default. Use the --verbose option for more information.

tilesets list <username>
  • --verbose: will list out the entire response object from the API
You can’t perform that action at this time.