Skip to content

Use with AI Agents

The CLI has been tested and tuned to work well with AI agents such as Claude Code. ConfigHub changes from release to release, so an agent does best when it looks up how the installed version behaves rather than relying on what it learned in training. Give your agent instructions like:

I'm using ConfigHub. Its CLI, cub, is in my path. Run CONFIGHUB_AGENT=1 cub --help-overview first, and read CONFIGHUB_AGENT=1 cub <command> --help before running any command.

Where an agent finds out how ConfigHub works

  • The agent overview. CONFIGHUB_AGENT=1 cub --help-overview prints an overview written for agents: the model, how commands are named and scoped, output formats, and how to make changes safely. cub --help points agents at it.
  • Command help. CONFIGHUB_AGENT=1 cub <command> --help describes the installed version of each command, with sections written for agents that the plain help leaves out. The help describes the cub that is installed, so it is the authority on what a command accepts.
  • Entity fields. cub <entity> explain lists an entity's fields, and cub <entity> explain <Field> describes one, from the API's own schema. These are the field names that -o json, -o jq=..., --select and --where use.
  • Functions. cub function list --space <space> lists the functions available in a space, and cub function explain <function> --space <space> describes one's parameters and behavior.
  • These docs, as raw markdown. Every page is served as markdown at https://docs.confighub.com/markdown/<path>.md. https://docs.confighub.com/markdown/index.md lists them by section, and https://docs.confighub.com/markdown/sitemap.json lists them with titles and sizes. The background/ pages explain concepts and entities, and the guide/ pages explain how to do things. The CLI reference is not in the markdown export; the command help is its source.

Giving an agent its own identity

An agent you run unattended, in a pipeline or as a long-running process, should act as a service account of its own rather than as you. Grant the service account only what the agent needs, and log in with its key:

cub serviceaccount create my-agent
cub serviceaccount key add my-agent --generate my-agent
cub auth login --private-key=my-agent

cub renews the service account's session from the key without a browser. Every change the agent makes is then attributed to the service account in Revisions, so you can tell its changes from yours, and you can revoke its access without touching your own. An agent working interactively with you can use your login instead; cub auth login opens a browser, so you run it yourself.

Agent skills

A skill for Claude Code is available at github.com/confighub/confighub-skills. It can be installed as a plugin:

claude plugin marketplace add https://github.com/confighub/confighub-skills
claude plugin install confighub-skills@confighub

In the future we may provide an MCP server endpoint, but we have found that using the CLI is quite effective.