<div align="center">
# querypie-cli
[](https://github.com/sudosubin/querypie-cli/releases)
[](https://docs.querypie.com)
[](LICENSE)
Query QueryPie databases from the terminal with webview authentication.
<a href="./docs/assets/querypie-cli-demo.avif">
<img src="./docs/assets/querypie-cli-demo.avif" alt="querypie-cli demo" width="1200" />
</a>
</div>
## Quick Start
```sh
querypie --host querypie.example.com auth login
querypie --host querypie.example.com connection list
querypie --host querypie.example.com query -c '<connection>' 'select 1;'
```
## Installation
Linux / macOS:
```sh
curl --proto '=https' --tlsv1.2 -fsSL https://github.com/sudosubin/querypie-cli/releases/latest/download/querypie-cli-installer.sh | sh
```
Windows (PowerShell):
```powershell
powershell -c "irm https://github.com/sudosubin/querypie-cli/releases/latest/download/querypie-cli-installer.ps1 | iex"
```
The installer (generated by [cargo-dist](https://github.com/axodotdev/cargo-dist)) is itself a versioned release asset — not a mutable branch file — downloads the matching binary from [GitHub Releases](https://github.com/sudosubin/querypie-cli/releases), verifies its checksum, and installs it to `.local/bin` under your home directory on every platform. Every release asset, including the installer scripts, carries a [GitHub Artifact Attestation](https://github.com/sudosubin/querypie-cli/attestations); verify one before running it with:
```sh
curl --proto '=https' --tlsv1.2 -fsSL -o querypie-cli-installer.sh https://github.com/sudosubin/querypie-cli/releases/latest/download/querypie-cli-installer.sh
gh attestation verify querypie-cli-installer.sh --repo sudosubin/querypie-cli
sh querypie-cli-installer.sh
```
Set `QUERYPIE_CLI_INSTALL_DIR` to change the install location.
Or install with Cargo:
```sh
cargo install querypie-cli
```
Build from source:
```sh
cargo build --release
```
`querypie` uses a WebView for login: Linux needs WebKitGTK (`libwebkit2gtk-4.1`) at runtime, and Windows needs the Edge WebView2 Runtime (preinstalled on current Windows).
## Commands
| Command | Purpose |
| --- | --- |
| `auth login` | Open the QueryPie WebView login |
| `auth logout` | Clear the WebView profile for a host |
| `auth status` | Show login status |
| `completion <shell>` | Generate shell completions |
| `connection list` | List available QueryPie connections |
| `database list` | List databases for a connection |
| `query <sql>` | Run SQL through QueryPie |
| `schema list` | List schemas for a database |
| `session clear` | Clear cached database sessions |
| `session list` | List cached database sessions |
| `table ddl <table>` | Show QueryPie table DDL |
| `table describe <table>` | Show QueryPie table structure |
| `table list` | List tables |
## Examples
```sh
querypie --host querypie.example.com connection list
querypie --host querypie.example.com database list -c '<connection>'
querypie --host querypie.example.com query -c '<connection>' --db example_db 'select 1;'
querypie --host querypie.example.com query -c '<connection>' --db example_db --limit 100 'select * from users;'
querypie --host querypie.example.com table describe -c '<connection>' --db example_db users
querypie --host querypie.example.com table list -c '<connection>' --db example_db
```
Use `--output json` for machine-readable output.
```sh
querypie --host querypie.example.com connection list --output json
```
## Authentication
- Login uses a dedicated Tauri WebView.
- httpOnly QueryPie cookies stay in the WebView cookie store.
- Access token refresh runs automatically in the background.
- If refresh fails for a previously authenticated host, commands open the login WebView and continue after login.
- If no login exists, commands exit with an auth error.
## Configuration
Default path:
```text
~/.config/querypie-cli/config.json
```
Example:
```json
{
"host": "querypie.example.com",
"connection": "example-main",
"database": "example_db"
}
```
CLI flags override config values.
## Shell Completions
Generate completions for your shell:
```sh
querypie completion bash > querypie.bash
querypie completion elvish > querypie.elv
querypie completion fish > ~/.config/fish/completions/querypie.fish
querypie completion powershell > _querypie.ps1
querypie completion zsh > "${fpath[1]}/_querypie"
```
Completions can query your logged-in QueryPie host for connection, engine, database,
schema, and table candidates. If authentication or network access is unavailable,
dynamic candidates are skipped silently.
## Output
- `--color auto|always|never`: control ANSI color (`auto` colors terminal output unless `NO_COLOR` is set)
- `--limit <N>`: maximum query rows to fetch, defaults to `1000` and must be at least `1`
- `--no-truncate`: do not shorten long table cells
- `--output json`: raw JSON output
- `--output text`: default human-readable output
- `QUERYPIE_NO_TRUNCATE=1`: disable truncation globally
`NULL` values are rendered distinctly in colored text output. JSON output never includes ANSI escape sequences.
Text query output reports `(N rows, limit reached)` when the result reaches the configured row limit. JSON query output includes `limit` and `limit_reached` fields alongside `columns` and `rows`.
## How It Works
1. `auth login` opens QueryPie in a Tauri WebView.
2. The CLI reads httpOnly cookies through the same WebView profile.
3. API calls use QueryPie's gRPC-Web endpoints.
4. Expired access tokens are refreshed through the WebView cookie store.
5. Database sessions are cached under `~/.cache/querypie-cli`.
## Troubleshooting
Check auth:
```sh
querypie --host querypie.example.com auth status
```
Clear cached database sessions:
```sh
querypie --host querypie.example.com session clear
```
## Development
```sh
cargo build --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
cargo test --all-features
```
## License
MIT, see [LICENSE](./LICENSE).