Skip to content
CLI for interacting with the Mapbox Tilesets API
Branch: master
Clone or download
samfader Merge pull request #14 from mapbox/sf-update-readme
Update readme to clarify how to update a tileset
Latest commit 932d005 Aug 14, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests Get tokens from the environment when commands are invoked Jul 31, 2019
tilesets Get tokens from the environment when commands are invoked Jul 31, 2019
.coveragerc hi Jul 24, 2019
.gitignore hi Jul 24, 2019
.python-version hi Jul 24, 2019
.travis.yml hi Jul 24, 2019 0.1.0 Aug 1, 2019 code of conduct (#4) Jul 25, 2019 hi Jul 24, 2019 add license Jul 25, 2019 Update Aug 14, 2019
codecov.yml hi Jul 24, 2019
requirements.txt Relax requirement specifiers Jul 31, 2019
setup.cfg hi Jul 24, 2019 0.1.0 Aug 1, 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


  • Python >= 3.6 (can be installed via virtualenv)
  • virtualenv (optional)

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



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


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
You can’t perform that action at this time.