socrata-cli 0.1.0

CLI for the Socrata Open Data API

socrata-cli

An unofficial command-line interface for the Socrata Open Data API (SODA).

Installation

Install the latest published release from PyPI:

uv tool install socrata-cli

or:

pip install socrata-cli

Requires Python 3.9+.

To install directly from GitHub before a PyPI release is available, or to test a development build that has not been published to PyPI:

uv tool install git+https://github.com/yonran/socrata-cli.git

Pin a tag for reproducible installs:

uv tool install git+https://github.com/yonran/socrata-cli.git@v0.1.0

Use PyPI for normal installation once a version has been released. Use GitHub URLs for unreleased changes, private testing, or exact commit installs.

Quickstart

# Query a dataset (by 4x4 ID or full URL)
socrata dataset query pitq-e56w --where "transaction_date > '2024-01-01'" --limit 50

# Download an entire dataset
socrata dataset download https://data.sfgov.org/resource/pitq-e56w --format csv

# Show dataset metadata
socrata dataset metadata pitq-e56w

# List columns
socrata dataset columns pitq-e56w

Configuration

Credentials

Create an API Key at https://<your-domain>/profile/edit/developer_settings, then add a credential set:

socrata config creds add mysf
# prompts for domain, Key ID, and Key Secret

Enable a credential set for its domain (only one active per domain at a time):

socrata config creds use mysf

Use --creds public to force unauthenticated access for a single invocation.

Default domain

Set a default domain so you can use bare 4x4 dataset IDs without a full URL:

socrata config domain set data.sfgov.org

When a full URL is provided, its domain is used directly and the matching enabled credential set is selected automatically.

Commands

socrata dataset query DATASET_REF

Query a dataset with optional SoQL filters.

Option	Description
--select	Columns to return ($select)
--where	Row filter ($where)
--order	Sort order ($order)
--group	Group by ($group)
--q	Full-text search
--limit	Max rows (default: 1000)
--offset	Pagination offset
--all	Fetch all rows (streams, ignores --limit)
-f / --format	table (default), json, csv
-o / --output	Write to file instead of stdout

socrata dataset download DATASET_REF

Stream all rows to a file.

Option	Description
-f / --format	csv (default) or json
-o / --output	Output file (default: <id>.<fmt>)

socrata dataset metadata DATASET_REF

Show dataset name, description, column types, and update timestamps.

socrata dataset columns DATASET_REF

List column names, types, and descriptions.

socrata config creds

Subcommand	Description
add NAME	Add or update a credential set
list	List all credential sets
use NAME	Enable a credential set for its domain
remove NAME	Delete a credential set and its stored keys

socrata config domain

Subcommand	Description
set DOMAIN	Set the default domain for bare dataset IDs
remove	Clear the default domain

Global Options

Option	Description
-c / --creds	Credential set to use for this invocation
--domain	Override domain for this invocation
--timeout	Request timeout in seconds (default: 10)

Releasing

This project publishes socrata-cli to PyPI from GitHub Actions using PyPI trusted publishing. No PyPI API token is stored in GitHub.

GitHub installs and PyPI releases serve different purposes:

Source	Use for
PyPI (uv tool install socrata-cli)	Normal public installs, dependency constraints, package mirrors, and stable releases
GitHub (uv tool install git+https://...)	Unreleased changes, private testing, and pinning an exact tag or commit before publishing

One-time PyPI setup:

1. Create or claim the socrata-cli project on PyPI.
2. Add a trusted publisher for the GitHub repository.
3. Use workflow filename .github/workflows/publish.yml.
4. Use environment name pypi.

To publish a release:

uv build --clear
git tag v0.1.0
git push origin v0.1.0

The publish workflow builds the source distribution and wheel, then uploads them to PyPI. PyPI attestations are enabled in the publish step and are tied to GitHub's OIDC identity for the workflow run.

License

MIT