The ParaQL CLI (paraql) is a terminal tool for running ParaQL queries against the Parascope API. It supports rich table output, multiple output formats, an interactive REPL with autocomplete, and saved queries.

Installation

Coming Soon — The ParaQL CLI will be available for installation via pip install paraql or pipx install paraql in an upcoming release. The documentation below describes the planned functionality.

Quick Start

# Run a query directly
paraql "SHOW TABLES"

# Select specific fields
paraql "SELECT name, ci_type FROM kubernetes.pod LIMIT 10"

# JSON output for scripting
paraql --format json "SELECT name FROM openstack.server"

# Start interactive REPL
paraql -i

Authentication

The CLI needs an API key to authenticate with Parascope. Configure it in one of three ways (highest priority first):

1. Command-line flag

paraql --api-key 'ps_svc_...' "SHOW TABLES"

2. Environment variable

export PARAQL_API_KEY='ps_svc_...'
paraql "SHOW TABLES"

3. Config file

Create ~/.paraql/config.toml:

[default]
api_key = "ps_svc_..."
endpoint = "https://your-company.parascope.io"

[dev]
api_key = "ps_svc_..."
endpoint = "https://your-company.parascope.io"
output_format = "json"

Switch profiles with --profile:

paraql --profile dev "SHOW TABLES"

Output Formats

Format	Flag	Use Case
`table`	`--format table`	Human-readable Rich tables (default)
`json`	`--format json`	Machine-readable JSON array
`csv`	`--format csv`	Spreadsheet import, piping
`value`	`--format value`	Single scalar for shell substitution

Examples:

# Rich table (default)
paraql "SELECT name, ci_type FROM kubernetes.pod LIMIT 5"

# JSON for jq processing
paraql -o json "SELECT name FROM openstack.server" | jq '.[].name'

# CSV for spreadsheets
paraql -o csv "SELECT name, ci_type FROM *" > export.csv

# Single value for scripts
COUNT=$(paraql -o value "SELECT COUNT(*) FROM kubernetes.pod")
echo "There are $COUNT pods"

Command Reference

Query Execution

# Direct query
paraql query "SELECT name FROM kubernetes.pod"

# Shorthand (no 'query' subcommand needed)
paraql "SELECT name FROM kubernetes.pod"

# From file
paraql query --file report.pql

# From stdin
echo "SHOW TABLES" | paraql query

Flags:

Flag	Short	Description
`--format`	`-o`	Output format: table, json, csv, value
`--limit`	`-l`	Add or override LIMIT clause
`--explain`		Show the generated SQL query plan
`--dry-run`		Parse and validate without executing
`--time`	`-t`	Show execution time in footer
`--no-header`		Suppress column headers
`--no-pager`		Disable auto-pager on TTY

Schema Inspection

# List all CI types
paraql show tables

# Filter by source
paraql show tables --source kubernetes

# Describe a CI type's fields
paraql describe openstack.server

# List relationship types
paraql show relationships

# Relationships for a specific CI type
paraql show relationships --for kubernetes.pod

# List data sources
paraql show sources

# List infrastructure tiers
paraql show tiers

Saved Queries

# List saved queries
paraql saved list

# Run a saved query
paraql saved run <query-id>

# Save a new query
paraql saved create --name "Pod count" --query "SELECT COUNT(*) FROM kubernetes.pod"

# With description and sharing
paraql saved create \
  --name "Critical CIs" \
  --query "SELECT name, criticality_score FROM * WHERE criticality_score > 80" \
  --description "High-criticality infrastructure items" \
  --shared

# Delete a saved query
paraql saved delete <query-id>

Interactive REPL

Start the REPL with paraql -i or paraql --interactive. When run without arguments in a terminal, the REPL starts automatically.

$ paraql -i
ParaQL connected to https://your-company.parascope.io
93 CI types across 5 sources. Type \? for help.

paraql> SHOW TABLES FROM kubernetes

Features

Tab completion -- context-aware suggestions for keywords, CI types, fields, and relationships
Syntax highlighting -- color-coded keywords, strings, numbers, and CI type references
Multiline editing -- end queries with ; for multi-line input
Persistent history -- queries saved to ~/.paraql/history between sessions

Backslash Commands

Command	Description
`\q`, `\quit`	Exit the REPL
`\format <fmt>`	Change output format for the session
`\tables`	Run SHOW TABLES
`\describe <type>`	Run DESCRIBE for a CI type
`\history`	Show recent queries
`\save <name>`	Save the last executed query
`\clear`	Clear the screen
`\?`, `\help`	Show available commands

Automation Examples

# Daily pod count in cron
0 8 * * * paraql -o value "SELECT COUNT(*) FROM kubernetes.pod" >> ~/reports/pod-count.log

# Export all servers to CSV
paraql -o csv --no-header "SELECT name, status FROM openstack.server" > servers.csv

# Check if critical CIs exist
if [ "$(paraql -o value 'SELECT COUNT(*) FROM * WHERE criticality_score > 90')" -gt 0 ]; then
  echo "Critical CIs found"
fi

# Pipe to jq for processing
paraql -o json "SELECT name, ci_type FROM kubernetes.pod" | \
  jq -r '.[] | "\(.name) (\(.ci_type))"'

ParaQL CLI

On this page