Metadata-Version: 2.3
Name: gable
Version: 0.70.0
Summary: Command line interface (CLI) and software development kit (SDK) to interact with Gable API
Author: Gable.ai
Author-email: engineers@gable.ai
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: all
Provides-Extra: mssql
Provides-Extra: mysql
Provides-Extra: postgres
Provides-Extra: s3
Requires-Dist: GitPython (>=3.1.47,<4.0.0)
Requires-Dist: boto3 (>=1.34.0,<1.35.0) ; extra == "s3" or extra == "all"
Requires-Dist: botocore (>=1.34.0,<1.35.0) ; extra == "s3" or extra == "all"
Requires-Dist: click (>=8.1.3,<9.0.0)
Requires-Dist: click-option-group (>=0.5.6,<0.6.0)
Requires-Dist: cryptography (>=48.0.1)
Requires-Dist: deepdiff (>=8.6.1,<9.0.0) ; extra == "s3" or extra == "all"
Requires-Dist: duckdb (>=1.2.2,<2.0.0) ; extra == "s3" or extra == "all"
Requires-Dist: fastavro (>=1.10.0,<2.0.0) ; extra == "s3" or extra == "all"
Requires-Dist: fsspec (>=2023.0.0,<2025.0.0) ; extra == "s3" or extra == "all"
Requires-Dist: giturlparse (>=0.10.0,<0.11.0)
Requires-Dist: h11 (>=0.16.0,<0.17.0)
Requires-Dist: jsonpickle (>=3.0.0,<4.0.0)
Requires-Dist: jsonref (>=1.1.0,<2.0.0)
Requires-Dist: loguru (>=0.7.0,<0.8.0)
Requires-Dist: mypy-boto3-apigateway (==1.38.0) ; extra == "s3" or extra == "all"
Requires-Dist: mypy-boto3-s3 (>=1.0.0,<2.0.0) ; extra == "s3" or extra == "all"
Requires-Dist: mysql-connector-python (>=9.1.0,<10.0.0) ; extra == "mysql" or extra == "all"
Requires-Dist: numpy (>=1.0.0,<2.0.0) ; extra == "s3" or extra == "all"
Requires-Dist: pandas (>=1.5.3,<3.0.0) ; extra == "s3" or extra == "all"
Requires-Dist: psycopg2-binary (>=2.7) ; extra == "postgres" or extra == "all"
Requires-Dist: pyarrow (>=23.0.1) ; extra == "s3" or extra == "all"
Requires-Dist: pycryptodome (>=3.17.0,<4.0.0)
Requires-Dist: pydantic[email] (>=2.0.0,<3.0.0)
Requires-Dist: pymssql (>=2.2.8,<3.0.0) ; extra == "mssql" or extra == "all"
Requires-Dist: python-snappy (>=0.7.3,<0.8.0) ; extra == "s3" or extra == "all"
Requires-Dist: pyyaml (>=6.0.0,<7.0.0)
Requires-Dist: recap-core[json,proto] (>=0.14.0,<0.15.0) ; python_version >= "3.10" and python_version < "3.15"
Requires-Dist: requests (>=2.33.0,<3.0.0)
Requires-Dist: rich (>=13.5.0,<14.0.0)
Requires-Dist: tqdm (>=4.67.1,<5.0.0)
Requires-Dist: urllib3 (>=2.7.0)
Requires-Dist: uuid6 (>=2025.0.1,<2026.0.0)
Description-Content-Type: text/markdown

# Gable CLI and SDK

`gable` is Gable on the command line. It publishes contracts, registers data assets and more.

```bash
gable --help
Usage: gable [OPTIONS] COMMAND [ARGS]...

Options:
  --endpoint TEXT  Customer API endpoint for Gable, in the format
                   https://api.company.gable.ai/
  --api-key TEXT   API Key for Gable
  --version        Show the version and exit.
  --help           Show this message and exit.

Commands:
  auth        View configured Gable authentication information
  contract    Validate/publish contracts and check data asset compliance
  data-asset  Commands for data assets
  ping        Pings the Gable API to check for connectivity
```

## Getting Started

`gable` is [hosted on PyPi](https://pypi.org/project/gable/), so to install it just run:

```bash
pip install gable
```

### Installing Additional Modules for MySQL and PostgreSQL

Gable's CLI allows you to introspect your database and register tables as data assets within Gable's system. Connecting to these databases require additional packages to communicate with your database(s) of choice.

For MySQL, install the additional packages by running:

```bash
pip install 'gable[mysql]'
```

For PostgreSQL, install the additional packages by running:

```bash
pip install 'gable[postgres]'
```

To install all additional dependencies at once, you can run:

```bash
pip install 'gable[all]'
```

## Uploading Lineage Results

Upload a single legacy results file with `--results-file`:

```bash
gable lineage upload --project-root . --namespace dev --results-file results.json
```

Referenced Prime artifacts require all three explicit file arguments:

```bash
gable lineage upload --project-root . --namespace dev \
  --strands-file strands.json \
  --metadata-file strand-metadata.json \
  --code-paths-file code-paths.json
```

Only explicitly named files are uploaded; sibling files are never discovered.
Incomplete artifact sets, missing files, and conflicting options are rejected before
any upload. Referenced artifacts cannot be combined with `--results-file` or
`--override-file`. Legacy `CODE_STRANDS` result files still use `--results-file`.

The referenced trio is packaged into one gzip-compressed tar stream and sent to
`/sca/results` through the existing chunk transport. There is no separate
declaration or completion call. The command succeeds only after the server
confirms that all three files are present and valid. Partial transfers are not
usable, and individual files cannot replace an existing set.

Retry the same command after an interruption. The CLI saves a small
`<strands-file>.upload-<identity>.json` retry-state file before uploading. Keep that
file to resume automatically. State is scoped to file contents and target, so a
different scan or endpoint does not reuse an unrelated run. No scan artifacts are
modified. Use `--run-id <UUIDv7>` to resume a known run explicitly or to request a
new run; different content under an existing run ID is rejected by the server.

## Setting up zsh/bash Autocomplete

The Gable CLI supports shell autocomplete for `zsh` and `bash` so you can hit `TAB` to see available commands and options as you write the command.

To enable it, run the following commands:

```bash
_SHELL=zsh # or bash
GABLE_CONFIG_DIR=~/.config/gable
mkdir -p $GABLE_CONFIG_DIR
_GABLE_COMPLETE=${_SHELL}_source gable > $GABLE_CONFIG_DIR/complete.sh
```

Then add the following to your shell startup scripts (e.g. `.zshrc`, `.bashrc`):

```bash
source ~/.config/gable/complete.sh
```

### Authentication

To establish an authenticated connection with Gable via the CLI, you need:

- The API endpoint associated with your organization
- An API key that corresponds to the endpoint

In order to find your API key and API endpoint, see the documentation in your Gable web app at (`/docs/settings/api_keys`).

There are two supported methods for providing this config to the CLI:

#### Authenticating with CLI Arguments

You have the option to pass the endpoint and API key information directly as arguments during the CLI invocation. For example:

```bash
gable --endpoint "https://api.yourorganization.gable.ai" --api-key "yourapikey" ping
```

#### Authenticating with Environment Variables

To avoid providing this config every time you execute a command, you can set them as environment variables: `GABLE_API_ENDPOINT` and `GABLE_API_KEY`. To make them persistent in your environment, add this to your shell initialization file (e.g. `.zshrc` or `.bashrc`):

```bash
export GABLE_API_ENDPOINT="https://api.yourorganization.gable.ai"
export GABLE_API_KEY="yourapikey"
```

Then, you can simply use the CLI as follows:

```bash
gable ping
```

### Accessing APIs Behind Proxies (Custom API Headers)

To access the Gable API behind corporate or customer proxies that require custom authentication, users can provide additional HTTP headers using the `GABLE_API_HEADERS` environment variable. This feature is essential for organizations whose infrastructure enforces proxy authentication or requires custom metadata in API requests.

#### Usage
Set the `GABLE_API_HEADERS` environment variable as a JSON string containing your custom headers:

```sh
export GABLE_API_HEADERS='{"Authorization": "Bearer YOUR_TOKEN", "X-Proxy-Header": "proxy-value"}'
```

When set, these headers are automatically included in every API request made by the CLI or client library. Custom headers will override default headers (such as `X-API-KEY`), allowing flexible integration with proxies, gateways, or custom authentication schemes.

#### Example
```sh
export GABLE_API_KEY=your_api_key
export GABLE_API_ENDPOINT=https://api.example.com
export GABLE_API_HEADERS='{"Authorization": "Bearer YOUR_TOKEN", "X-Proxy-Header": "proxy-value"}'
gable ping
```

