The command line¶
Installing fastgeoapi puts one command on your path. It has four subcommands, and which one you run decides what the process is allowed to do — that is the whole design, not an accident of packaging.
| Command | What it starts | Can it change what is served? |
|---|---|---|
fastgeoapi run | the server | no — it only reads the configuration |
fastgeoapi openapi | nothing; writes a document | no |
fastgeoapi config edit | the editor, on loopback | it writes; it cannot activate |
fastgeoapi config ingest | nothing; writes resources | it writes; it cannot activate |
fastgeoapi run¶
Serve the API.
fastgeoapi run
fastgeoapi run --host 127.0.0.1 --port 8000
fastgeoapi run --reload
fastgeoapi run --workers 4
fastgeoapi run --graceful-timeout 30
| Option | Default | Meaning |
|---|---|---|
--host, -h | 0.0.0.0 | address to bind |
--port, -p | 5000 | port to bind |
--reload, -r | off | restart on code changes; forces one worker |
--workers, -w | 1 | worker processes; with more than one, run turns on the configuration poll (FASTGEOAPI_CONFIG_POLL_SECONDS=5 unless you set it) so that a reload reaches every worker within that interval; see Hot reloading when there is more than one worker |
--graceful-timeout | 10 | seconds a shutdown (a Ctrl-C, or a restart under --reload) waits for the running requests; then uvicorn cancels them and they answer 500. A cancelled request interrupts its DuckDB query; with other providers the process still waits, before it exits, for the work already started |
The configuration it reads comes from PYGEOAPI_CONFIG (or the DEV_/PROD_ variant for your ENV_STATE), and it may be a local path or a bucket URL — see Config from cloud storage.
fastgeoapi openapi¶
Write the OpenAPI document, with fastgeoapi's security schemes folded into what pygeoapi generates.
Useful in CI, where the document can be linted or diffed before a change reaches a deployment. It reads the same configuration run would.
fastgeoapi config edit¶
Open the configuration editor. Covered in full in Editing the configuration; the short version:
fastgeoapi config edit
fastgeoapi config edit --source s3://my-bucket/pygeoapi-config.yml
fastgeoapi config edit --port 9000
| Option | Default | Meaning |
|---|---|---|
--source, -s | your configured document | what to edit; a path or a bucket URL |
--port, -p | 8765 | port for the editor |
--augmented | off | also report what fastgeoapi adds |
It works with only pygeoapi installed¶
Installing fastgeoapi to edit a pygeoapi document is a reasonable thing to want: the dry run builds the whole API and reads every data source, which nothing upstream offers. So config edit asks for no fastgeoapi configuration at all — no HOST, no PORT, no .env, no authentication chain. Point it at a document and it opens.
--augmented is the opt-in for the other side of that line. It adds what only fastgeoapi can say about a configuration: which OGC API specifications it would mount, since the route table is built from the resources rather than serving everything, and which MCP tools an agent would see, derived from the OpenAPI the dry run has already built.
Asking for it where it cannot be answered is not an error — the answer carries a line saying which half is missing and why, rather than failing and handing back the barrier this command exists without.
It prints a per-run token and the address to open. There is no --host: the editor refuses to serve anywhere but loopback, and that refusal is a startup failure rather than a warning, because it is what stands in for the authentication chain it deliberately does not have.
fastgeoapi config ingest¶
Write pygeoapi resources for the GeoParquet and PMTiles collections of a Portolan catalog, printed or merged into a configuration. It needs the portolan extra, and is covered in full in Ingesting a Portolan catalog.
fastgeoapi config ingest --from-portolan https://example.org/catalog/
fastgeoapi config ingest --from-portolan ./catalog --into pygeoapi-config.yml --prune
fastgeoapi config ingest --from-portolan s3://my-bucket/catalog/ --store-option region=eu-west-1 --json
| Option | Default | Meaning |
|---|---|---|
--from-portolan | required | the catalog: its catalog.json or the folder that holds it, as a path or a URL |
--into | none | the configuration to merge the resources into, a path or a bucket URL, with file indexes in indexes/ beside it; without it, the resources are printed |
--collection | all | ingest this collection only; repeat for more |
--prefix | none | put this before every resource id |
--store-option | none | a storage option for the buckets, as key=value; repeat for more |
--id-field | guessed | the id column of a collection, as collection=column, when the catalog names none |
--geometry-column | guessed | the geometry column of a collection, as collection=column, when the catalog names none |
--check-ids | off | count, in each GeoParquet collection, the rows that repeat an id or have none, reading the id column only; needs duckdb |
--prune | off | with --into, remove this catalog's resources whose collection is gone from it, and their file indexes |
--strict | off | exit with 1, before writing, when a collection is skipped or --check-ids finds a problem |
--json | off | print the summary as JSON |
--max-documents | 10000 | the most documents one walk reads, and the most items read for one collection |
--max-document-bytes | 33554432 | the largest document read, in bytes (32 MiB) |
Without --into the resources go to stdout and the summary to stderr; with it, the summary goes to stdout. It exits with 0 even when some collections were skipped, with 1 on an error, when nothing is written, and with 2 on a wrong command line.
portolan fastgeoapi ingest is the same command loaded by portolan-cli, with the same options.
Two roles, one program¶
run and config edit are the same project started differently, and neither can do the other's job. The serving role carries no editor; the authoring role carries no reload webhook, so it can write a configuration but never put one into service.
config ingest is on the authoring side too: it writes a configuration and never puts it into service.
The separation is tied to the command rather than to a setting on purpose. A variable can be set by mistake in production — it has happened here, PROD_ where DEV_ was read, and it cost a deployment — while a container's CMD does not reach a different subcommand unless somebody rewrites it.