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 downis 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 --allin any form, with or without--rm,--purgeor--yes, anddown --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, thencass-reset --yesandkafka-reset --yeswhen they apply, thendown --purge. While other projects still use the shared services, the project's Keycloak realm stays behind until someone runsgc. - If another project still uses the shared services,
down --purgeexits1and leaves them running. That is the expected result. quinectl gc --dry-run --jsonis read-only; a realgcneeds the same go-ahead as a removal.- Nothing waits for input: without a terminal, a command that would prompt stops at once with exit
2and names--yes. That isn't permission to add--yes: use it only for commands the agent may run on its own, such ascass-resetandkafka-reseton its own project. See Scripting and CI.
Next steps¶
- See what
--agentpicks, and how projects share a machine: Multi-tenancy. - Exit codes, JSON output and prompts in scripts: Scripting and CI.