Skip to content

Using quinectl from AI Agents

quinectl carries its own guide for AI coding agents and other automation, so an agent that has only the binary can learn to use it. It can also choose settings for an agent's project that stay clear of your own deployments on the same machine.

The built-in guide

To print the guide:

quinectl agent

The guide is self-contained Markdown, written for an agent to read before it runs anything. It covers prerequisites, every command, the configuration, exit codes, output streams, and the rules for stopping and removing things safely. Two machine-readable forms sit beside it:

Command Prints
quinectl agent The guide, as Markdown
quinectl agent --json Every command and flag, exit codes, environment variables, files written, prerequisites with a command to check most
quinectl agent --schema The quinectl.yaml schema: every field, its type, required fields, allowed values, defaults

None of them reads a quinectl.yaml or touches Docker, so an agent can run them at any time.

To start, tell the agent: "Run quinectl agent and follow it."

Settings that stay clear of yours

A project of your own that keeps quinectl's defaults uses port 8080, keyspace quine and realm quine-enterprise, so an agent's project should use other values, which init --agent picks. In a new directory:

mkdir agent-run && cd agent-run
quinectl init --agent
quinectl up

--agent picks the ports, keyspace and realm from the directory's path instead of the defaults, and suggests a proxy port and Kafka namespace; Let quinectl pick the values lists what it picks.

Rules worth giving an agent

The guide states these rules itself. They're repeated here so you know what to expect:

  • Plain quinectl down is always safe: it stops only the agent's own project.
  • Before any machine-wide removal, preview it: quinectl down --all --purge --dry-run --json.
  • An agent runs down --all in any form, with or without --rm, --purge or --yes, and down --orphans, only when a person asks. They can stop or remove containers and data that belong to other projects on the machine.
  • To tear down a project it created, an agent runs down, then cass-reset --yes and kafka-reset --yes when they apply, then down --purge. While other projects still use the shared services, the project's Keycloak realm stays behind until someone runs gc.
  • If another project still uses the shared services, down --purge exits 1 and leaves them running. That is the expected result.
  • quinectl gc --dry-run --json is read-only; a real gc needs the same go-ahead as a removal.
  • Nothing waits for input: without a terminal, a command that would prompt stops at once with exit 2 and names --yes. That isn't permission to add --yes: use it only for commands the agent may run on its own, such as cass-reset and kafka-reset on its own project. See Scripting and CI.

Next steps