Schema and readiness | Cefense docs

An agent arriving in an unfamiliar repository has two questions before it runs anything useful. What can this tool do, and can I do it here. There is a command for each.

Bothbash

cf agent schema
cf agent check --repo acme/api

cf agent schema

One JSON document describing the entire interface, generated from the CLI you actually have installed rather than written down somewhere and left to drift. cf agent on its own prints it, because it is what you almost certainly wanted.

commandsarray: The whole command tree: every command and subcommand with its path, what it does, its arguments, and its own options. The flags that work everywhere are listed once rather than repeated on all of them.
envelopeobject: The success and failure shapes, what goes on stdout and what goes on stderr, and the rules that hold for both.
errorsarray: Every error code the CLI can return. The same list as Errors and recovery, in a form you can branch on without parsing prose.
preconditionsarray: The states that stop a command before it starts, such as not being signed in or not having named a repository.
enumsobject: The accepted values: severities, categories, scan modes, intervals, depths, checks, merge methods, export formats. Read these rather than guessing at a spelling.
gatesarray: The actions that need a person, and what each one needs. Publishing, merging, attesting, and installing a skill need --yes. Triaging needs the user's actual decision. Changing settings, upgrading a plan, and scanning a URL need the user's agreement.
workflowsarray: Named sequences for the things agents are usually asked to do: triage a finding, patch one, gate a build, check a regression.
exitCodesobject: What each exit code means, so a failure can be classified without reading the message.

cf agent check

The second question. It answers whether an agent can proceed here, and when it cannot, exactly what has to happen first and who has to do it.

reachableboolean: Whether the instance answered at all.
authenticatedboolean: Whether there is a usable session, and who it belongs to.
repositorystring: Which repository the command resolved to, with repositorySource saying whether that came from the flag or the environment. In agent mode there is nothing else it could come from.
repositoryCountnumber: How many repositories the organization has connected, which is what distinguishes a fresh account from a misspelled repository.
providersarray: The state of each code host, so a missing connection is reported as a missing connection rather than as an empty list.
readyboolean: Whether to carry on. Branch on this.
blockersarray: Everything standing in the way, each with a code, what it is, a remedy, and whether the agent can clear it or the user has to.

That last field is the point of the command. Not being signed in is the user's job, and an agent should say so and wait. Not having named a repository is the agent's own job, and an agent should fix it and carry on. Reporting the two the same way is how an agent ends up asking a person to do something it could have done itself.

Where these fit in a session

cf agent check --repo <owner/name> first. If it is not ready, act on the blockers and stop rather than running the next command and reading a confusing failure.
cf agent schema when you need a value, a flag, or a command you are not sure of. Cheaper and more reliable than guessing and handling the refusal.
cf org list --agent before anything that writes, for the slug and the role. See Agent commands.

Agent modeThe envelope, the guarantees, and the gates.Agent commandsWhat each command returns, and what it hands you next.Errors and recoveryEvery code, and what to do about each one.

Have a correction or need help?

Email the docs team