Metadata-Version: 2.4
Name: socrata-cli
Version: 0.1.0
Summary: CLI for the Socrata Open Data API
Author: Yonathan Randolph
Author-email: Yonathan Randolph <yonathan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Dist: typer[all]>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: sodapy>=2.2
Requires-Dist: keyring>=25.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: requests>=2.31
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/yonran/socrata-cli
Project-URL: Repository, https://github.com/yonran/socrata-cli
Project-URL: Issues, https://github.com/yonran/socrata-cli/issues
Description-Content-Type: text/markdown

# socrata-cli

An unofficial command-line interface for the [Socrata Open Data API (SODA)](https://dev.socrata.com/).

## Installation

Install the latest published release from PyPI:

```sh
uv tool install socrata-cli
```

or:

```sh
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:

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

Pin a tag for reproducible installs:

```sh
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

```sh
# 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:

```sh
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):

```sh
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:

```sh
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:

```sh
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
