Skip to content

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 $(...).

  • up returns once every product is ready, and leaves them running in the background. Pressing Ctrl-C during up cancels what it is doing but never stops a product it already launched. If the product exits or crashes while starting, up fails straight away and names the log to read, instead of waiting out the timeout.
  • --timeout sets how long up waits for each service. The default is five minutes, enough for a first run that pulls images.
  • quinectl down stops 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, a status report, a JSON document, or a token.
  • stderr carries everything else: progress (→), success (✓), warnings, and errors (error:). The plain status report is the exception: its closing → and ✓ lines are part of the report, on stdout. What -v adds goes to stderr, so status -v --json still 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 includes down --rm or down --purge without --all refusing because a member may still be running or another project uses a shared service, and trust or trust --remove on Linux or Windows once quinectl has created its local certificate authority.
  • 2: Nothing was changed. The command itself needs fixing: there is no quinectl.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 as cass-reset without Cassandra, kafka-reset without local Kafka, token without Keycloak, or trust before 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