Scripting and CI¶
quinectl is built to be run from scripts as well as by hand. It never waits for input it can't get, it keeps its real output apart from progress messages, and the reports a script needs have a JSON form (see the table below).
A typical script¶
This script starts the project, runs one Cypher query against it, and stops its members when it ends:
set -e
export QE_LICENSE_KEY QE_CUSTOMER_ID
trap 'quinectl down' EXIT
quinectl up
curl -sf -X POST http://localhost:8080/api/v2/graph/quine/cypher:query \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $(quinectl token)" \
-d '{"text":"RETURN 1"}'
The trap runs quinectl down when the script ends, even if a step fails.
The script expects a quinectl.yaml with Keycloak auth in the working directory. Without Keycloak auth,
leave out the Authorization line: quinectl token fails there, and set -e doesn't catch a failure
inside $(...).
upreturns once every product is ready, and leaves them running in the background. Pressing Ctrl-C duringupcancels what it is doing but never stops a product it already launched. If the product exits or crashes while starting,upfails straight away and names the log to read, instead of waiting out the timeout.--timeoutsets how longupwaits for each service. The default is five minutes, enough for a first run that pulls images.quinectl downstops only this directory's members, so it is safe at the end of every job.
Output streams¶
- stdout carries only the command's result: a generated
quinectl.yaml, astatusreport, a JSON document, or a token. - stderr carries everything else: progress (
→), success (✓), warnings, and errors (error:). The plainstatusreport is the exception: its closing→and✓lines are part of the report, on stdout. What-vadds goes to stderr, sostatus -v --jsonstill parses.
So quinectl status --json | jq . and quinectl generate-config > quinectl.yaml never mix in a
progress line. Color is off automatically when output isn't a terminal. NO_COLOR turns it off unless
you pass --color=always. --color=never turns it off too, except for the error line when a command or
flag isn't recognized. To keep color in a pipe, for a CI log, use --color=always or set FORCE_COLOR=1.
JSON output¶
| Command | JSON form |
|---|---|
quinectl status --json |
Services, members, Kafka topics with ready-to-run ingest requests |
quinectl token --json |
Token, type, expiresIn, user, token endpoint |
quinectl version --json |
Version, commit, build date, platform, verified Quine release line |
quinectl down --dry-run --json |
What a down would stop and remove, and anything it would refuse |
quinectl gc --dry-run --json |
What gc would clean up |
quinectl generate-quine-conf --dry-run --json |
The configuration files written, and any warnings |
quinectl trust --status --json |
Whether the local certificate authority is trusted (macOS only) |
quinectl agent --json |
Every command and flag, exit codes, environment variables, prerequisites |
quinectl agent --schema |
The quinectl.yaml schema |
Fields may be added in later releases; existing fields keep their meaning.
Exit codes¶
quinectl exits with one of three codes:
0: Success, including a run that found everything already as configured.1: Something failed, or you answered no to a confirmation. This includesdown --rmordown --purgewithout--allrefusing because a member may still be running or another project uses a shared service, andtrustortrust --removeon Linux or Windows once quinectl has created its local certificate authority.2: Nothing was changed. The command itself needs fixing: there is noquinectl.yaml, the configuration is invalid, a flag is unknown or misused, or a confirmation was needed and there was no terminal to ask and no--yes. It also covers a command with nothing to act on, such ascass-resetwithout Cassandra,kafka-resetwithout local Kafka,tokenwithout Keycloak, ortrustbefore quinectl has created its local certificate authority.
The one exception: a refused or declined down --all --rm or down --all --purge has already taken this
directory off quinectl's records. Until the next quinectl up here, gc counts its keyspace, realm and
topics as unused, so run up before gc.
Prompts never hang¶
Commands that delete data or change your keychain (cass-reset, kafka-reset, gc, trust) ask for
confirmation. With no terminal attached, they don't wait: they exit 2 and tell you to pass --yes.
cass-reset also refuses while a product is running: it exits 1, so run quinectl down first.
down --all --rm and down --all --purge behave the same way when other directories use the services.
When this is the only directory on the machine, they go ahead at once, with no question and no --yes.
init and generate-config ask which edition to use only when the directory holds jars of both editions
and you didn't pass --edition; without a terminal, they exit 1 with an error and write nothing.
Pass --yes only for things you mean to delete. down and gc can preview with --dry-run; cass-reset
and kafka-reset have no preview.
Next steps¶
- Let an AI coding agent drive quinectl: Using quinectl from AI Agents.
- Look up every command's flags: Command Reference.