Skip to main content
Print the engine version, contract versions, and json-capable commands. capabilities is the handshake an agent or script runs before anything else. One call tells the caller which CLI it is talking to, which contract schemas that CLI writes, and which commands accept --output json. It needs no project, no session, and no browser.

​
When to use capabilities

  • An agent starts a session and must know which schema versions to parse.
  • A script wants to feature-detect --output json support instead of guessing by version.
  • You want to confirm which CLI build a npx invocation actually resolved.

​
Usage

​
Arguments and flags

This is the only command that defaults to json. A handshake exists for machines, so the machine format is the default and --output pretty is the opt-in.

​
What it returns

The JSON output is a schema-1 envelope (see Result envelope) whose value carries six fields:
outputJsonCommands and recordStreamCommands are read off the live command registrations, never a hand-kept list, so they cannot drift from what the CLI actually accepts. Treat the example above as illustrative and parse the real answer. A reader that expects one envelope on stdout must skip the commands in recordStreamCommands, which print log records on success and an envelope only on failure. Pretty output prints the same facts as five labeled lines. Both formats exit with code 0.

​
Typical agent flow

  1. Run extension capabilities and check envelopeSchema and readySchemaVersion are versions that you support.
  2. Start the session: extension dev --allow-control --output json.
  3. Drive it with the act verbs: inspect, eval, storage, reload.

​
Next steps

  • Read the envelope that every json-capable command emits in Result envelope.
  • Start the session that the handshake prepares for with dev.
  • Read the wider debugging workflow in Debugging.