Roger Chien

Posted on Apr 27

archery-cli: A psql-style CLI for Archery — Query Databases from Terminal or AI Agents

#ai #cli #showdev #sql

If you've ever copy-pasted query results from a web UI just to paste them into ChatGPT, this might save you that step.

At my company, we use Archery for SQL audit and read-only queries against our databases.

Archery has a nice web UI, but our AI tools (Claude Code, Cursor, Codex) cannot use a web UI. So I built archery-cli: a small psql-style command line client that wraps Archery's HTTP API. Both humans and AI agents can use it from the shell.

Why a CLI?

A CLI is the easiest way to bring AI tools into a workflow that already exists.

AI agents already know how to run shell commands.
A psql-style interface is familiar to engineers.
It does not bypass Archery — every query still goes through the same audit endpoint.

So we keep the audit flow, and the AI gets a tool it can actually use.

What it does

Run SELECT queries against any database that Archery exposes.
psql-style meta commands: \l, \dt, \d <table>, \dn.
Multiple output formats: aligned table (default), CSV, JSON, and expanded (-x) for wide rows.
DB name aliases, e.g. prod=db_orders_prod, so you can type archery prod instead of the full name.
Read SQL from -c, from a file with -f, or from stdin.
One static Go binary. No runtime dependency.

archery mydb -c 'SELECT count(*) FROM orders'
archery mydb -c 'SELECT * FROM users LIMIT 10' --csv > users.csv
echo 'SELECT version()' | archery mydb
archery mydb -c '\dt'

AI integration

The repo ships a skill file: archery.skill.md.

For Claude Code, drop it into your skills folder:

curl -O https://raw.githubusercontent.com/rjchien728/archery-cli/main/skills/archery.skill.md
mv archery.skill.md ~/.claude/skills/

For other AI tools (Cursor, Windsurf, Codex…), the skill file is plain Markdown. Paste it into the tool's system prompt or custom instructions.

After that, your AI can answer real data questions on its own:

You: How many orders came in last week in prod?

Claude: runs archery prod -c 'SELECT count(*) FROM orders WHERE created_at > now() - interval 7 day'

Claude: 12,483 orders last week.

Security details

This tool talks to a real production audit platform, so I want to be careful. Here is what archery-cli does:

SELECT-only. Archery's /query/ endpoint blocks DML and DDL on the server side. The CLI documents itself as a read-only client and does not try to work around that.
No password in argv. There is no --password flag on purpose. Credentials never appear in ps output or shell history.
Password prompt on /dev/tty. If ARCHERY_PASSWORD is not set, the CLI asks for it on the terminal — even when stdin is a pipe. CI and containers should set the env var; humans get a normal prompt.
Cookie cache with strict permissions. After login, the session cookie is saved to ~/.cache/archery/cookies.json with mode 0600. If the home directory is not available, the CLI fails fast instead of falling back to an unsafe path.
TLS by default. For internal deployments, --cacert lets you trust a private CA. There is also --insecure to skip verification, but it is clearly marked as unsafe in the help text and README.
CSRF handled the Django way. The CLI reads the csrftoken cookie from its jar and sends it as X-CSRFToken on each request, like a normal Archery web client.
Proxy support. Honours HTTPS_PROXY / HTTP_PROXY, with native support for socks5:// and socks5h://.

These are small details, but together they keep the tool safe enough to run in a real engineering team.

Try it

go install github.com/rjchien728/archery-cli/cmd/archery@latest

Or grab a binary from the releases page.

Set a few environment variables (ARCHERY_URL, ARCHERY_INSTANCE, ARCHERY_USERNAME, ARCHERY_PASSWORD) and you are ready to go. Full setup is in the README.

Closing

archery-cli is open source under the MIT license. If your team also uses Archery and wants AI tools to query databases without leaving the audit flow, give it a try:

Repo: github.com/rjchien728/archery-cli
Issues and PRs are welcome.

Does your team use a similar setup? I'm curious what SQL audit tools other people are using, and how you connect AI tools to them — drop a comment below.

DEV Community