Metadata-Version: 2.4
Name: paraql
Version: 0.1.0
Summary: Command-line client for Parascope: run ParaQL queries, browse schema, and script exports
Project-URL: Homepage, https://parascope.io
Project-URL: Documentation, https://parascope.io/docs/cli
Project-URL: Changelog, https://parascope.io/docs/changelog
Author-email: Parascope <ops@parascope.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,cmdb,infrastructure,paraql,parascope
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
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 :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: click<9,>=8.1
Requires-Dist: httpx<0.29,>=0.25.0
Requires-Dist: prompt-toolkit<4,>=3.0.0
Requires-Dist: rich<16,>=13.0.0
Requires-Dist: typer<0.28,>=0.26.0
Description-Content-Type: text/markdown

# paraql

`paraql` is the command-line client for [Parascope](https://parascope.io), a CMDB that
discovers your infrastructure and maps how it fits together. It runs ParaQL queries against
your tenant's API and prints the answer as a table, JSON, CSV, or a bare value you can pipe
into the next command.

The PyPI package named `parascope` is unrelated to this project and is not published by us.
This client is `paraql`.

## Install

```bash
pip install paraql
```

Or, to keep it in its own environment:

```bash
pipx install paraql
```

## Connecting

`paraql` talks to your Parascope tenant, so it needs two things: the tenant endpoint
(`https://<slug>.parascope.io`) and an API key. There is no built-in default endpoint; if
neither is configured, `paraql` says so and exits instead of guessing.

The guided setup writes `~/.paraql/config.toml` with mode 0600:

```bash
paraql config init
```

Environment variables work too, and are handy in CI:

```bash
export PARAQL_ENDPOINT="https://acme.parascope.io"
export PARAQL_API_KEY="ps_ro_..."
```

Command-line flags win over environment variables, which win over the config file. Check what
resolved, with the key masked:

```bash
paraql config show
```

The endpoint must be `https`. Plain `http` is accepted for local addresses such as
`localhost`, or elsewhere if you pass `--insecure`, which sends the API key in the clear.

`--timeout` and `--insecure` are group-level flags, so they go before the subcommand:

```bash
paraql --timeout 120 query "SELECT name FROM kubernetes.pod"
```

## Running a query

```bash
paraql "SELECT name, namespace FROM kubernetes.pod WHERE config.phase = 'Running' LIMIT 10"
```

A bare query is shorthand for `paraql query`. Pick a format with `-o` and the result becomes
scriptable:

```bash
paraql -o json "SELECT name, criticality_score FROM openstack.instance" | jq '.[].name'
```

## Interactive mode

`paraql -i` opens a REPL with persistent history and schema-aware completion. Running `paraql`
with no arguments in a terminal does the same. Inside it, `\?` lists the backslash commands and
`\q` quits.

```
$ paraql -i
paraql> SHOW TABLES
paraql> SELECT name, ci_type FROM kubernetes.pod LIMIT 5
paraql> \q
```

## Documentation

- CLI reference: `https://<slug>.parascope.io/docs/cli`
- ParaQL language reference: `https://<slug>.parascope.io/docs/paraql-reference`

`paraql --help` lists the subcommands, and `paraql <subcommand> --help` covers each one.

## License

Apache-2.0. See [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
