ZeroRoot Docs

CLI Reference

Complete reference for every gibson command, flag, and default, generated from the CLI.

gibson is the local command-line interface for the Gibson platform. This page lists every command exhaustively; the guides walk you through the common workflows.

gibson — tooling for the Gibson agent / tool / plugin
development lifecycle.

Subcommands:
  login      authenticate the CLI against the platform (device flow)
  logout     end the CLI session and remove stored credentials
  init       initialize a Gibson workspace (.gibson/workspace.yaml)
  component  scaffold, validate, build, run components (agent | tool | plugin)
  connector  enable and manage tenant connectors (catalog | enable | list | disable)
  docs       emit machine-readable docs (JSON Schemas, etc.)
  inspect    show what this principal can do (calls WhoAmI)
  mission    author, validate, render, submit gibson missions
  target     create, list, inspect, update, delete assessment targets
  agent      manage agent/tool/plugin machine identities

Global flags

Available on every command.

FlagTypeDefaultDescription
--ca-certstring—PEM file with a CA certificate to trust IN ADDITION to the system store (env: GIBSON_CA_CERT)

Commands

gibson agent

Manage agent/tool/plugin machine identities (AgentIdentityService)

gibson agent — provision and manage machine identities for
agents, tools, and plugins via AgentIdentityService on the Gibson
daemon. Authenticated as you: run `gibson login` first.

Subcommands:
  enroll  provision a new machine identity and print the one-time secret
  list    list all identities for the tenant
  revoke  permanently revoke an identity by principal ID

gibson agent enroll

Provision a new machine identity and print the one-time bootstrap token

Call AgentIdentityService.CreateAgentIdentity to provision a new
machine identity, authenticated as you (run `gibson login` first).
The one-time bootstrap token is printed to stdout — store it immediately;
it cannot be retrieved again. Pass it to the component as
GIBSON_BOOTSTRAP_TOKEN and start the binary once: it completes the
capability-grant handshake itself (ADR-0045, sdk#128). The same flow serves
every component kind.

Flags

FlagTypeDefaultDescription
--capabilitystringArray—Session capability to grant in the credential ceiling; repeatable. Reserved names: mission:originate (start its own mission), mission:delegate
--descriptionstring—Human-readable description
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--kindstringagentComponent kind: agent | tool | plugin
--namestring—Identity name (required)
--timeoutduration30sRPC deadline

gibson agent list

List all machine identities for the tenant

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--kindstring—Filter by kind: agent | tool | plugin (default: all)
--timeoutduration30sRPC deadline

gibson agent revoke

Permanently revoke a machine identity

Call AgentIdentityService.RevokeAgentIdentity. The identity is
immediately invalidated; existing JWTs for the principal stop being
accepted by the daemon. This action is irreversible.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRPC deadline

gibson component

Scaffold, validate, build, and run Gibson components (agent | tool | plugin | connector)

component — kind-aware tooling for the Gibson developer workflow.

Subcommands:
  init      scaffold a new component directory from templates
  generate  regenerate gen/ from taxonomy.yaml and ontology.yaml
  build     generate + validate + go build (one-step developer loop)
  validate  local schema + proto checks against a component directory
  run       run the compiled component binary, supervising its signals

--kind is required on validate and run. It used to be auto-detected from
component.yaml, which no longer exists (ADR-0097): everything else about a
component is implied by its directory, and the kind is not.

A component enrols itself at boot from GIBSON_URL and
GIBSON_BOOTSTRAP_TOKEN (sdk#128), so there is no register verb.

gibson component build

Generate, validate, and compile the component binary

build is the one-step developer loop command:

  1. generate  — regenerate gen/ from taxonomy.yaml + ontology.yaml
  2. validate  — run all local checks (main.go parses, proto field 100,
                 buf lint, ontology YAML parse)
  3. proto     — run buf generate when buf.gen.yaml exists and api/gen
                 is missing or older than api/proto (needs buf,
                 protoc-gen-go and protoc-gen-go-grpc on PATH)
  4. mod tidy  — populate go.sum on a freshly scaffolded component
                 (skipped once go.sum exists)
  5. go build  — compile the component binary into the component directory

build delegates to the generate and validate subcommands, resolves
modules when go.sum is absent, then runs `go build ./...` in the
component directory. Use `gibson component generate`
or `gibson component validate` individually if you want finer control.

Exit codes:
  0  build succeeded
  1  generate / validate / compile error (details on stderr)

--kind is required, because step 2 is kind-aware and the kind used to come
from component.yaml, which no longer exists (ADR-0097).

Examples:
  gibson component build --kind tool
  gibson component build --kind plugin --dir ./my-plugin

Flags

FlagTypeDefaultDescription
-d, --dirstring.component directory
--kindstring—component kind: agent | tool | plugin (required)

gibson component generate

Generate Go bindings from taxonomy.yaml and ontology.yaml

generate reads taxonomy.yaml and ontology.yaml (if present) in the
component directory and emits Go source files under gen/:

  gen/ontology_extension.go  — exports OntologyExtension() returning a
                               graphrag.OntologyExtension populated from
                               the parsed ontology.yaml

Generated files are byte-stable across runs: map keys are sorted and
go/format is applied. Commit the gen/ directory; diffs reflect only
intentional ontology changes.

generate is a no-op if neither YAML file is present (it prints a notice
and exits 0 rather than failing).

Examples:
  gibson component generate
  gibson component generate --dir ./my-tool

Flags

FlagTypeDefaultDescription
-d, --dirstring.component directory

gibson component init

Scaffold a new component directory (agent | tool | plugin | connector)

init scaffolds a new Gibson component directory from embedded
templates. The kind selects which template set to render and what file
shape the new directory has:

  agent:      main.go (sdk.NewAgent + sdk.ServeAgent) +
              go.mod + Makefile + Dockerfile + README + AGENTS.md +
              CLAUDE.md + prompts/ + .claude/settings.json

  tool:       like agent, plus api/proto/gibson/tools/<pkg>/v1/<pkg>.proto
              with field 100 = gibson.graphrag.v1.DiscoveryResult, buf.yaml,
              buf.gen.yaml, and proto/vendor/ for the SDK protos

  plugin:     Go-first (ADR-0065 R4). handler.go declares the plugin in
              code (plugin.Serve + WithName, WithVersion, WithHandler, typed
              Go request/response structs — no .proto, no manifest file,
              ADR-0097) + a hermetic handler_test.go with a
              committed cassette under testdata/ + helm/values.yaml +
              go.mod + Makefile + Dockerfile + README + AGENTS.md +
              CLAUDE.md + prompts/ + .claude/settings.json

  connector:  Declarative (ADR-0065 R6). connector.yaml manifest (the
              integration IS the manifest — no Go code) + a hermetic
              schema-validation smoke test (connector_test.go) + go.mod +
              README + AGENTS.md + CLAUDE.md + .claude/settings.json

The name must match ^[a-z][a-z0-9-]{0,61}[a-z0-9]$ (DNS-label style).

--with-secret is plugin-only. It names a broker secret that the plugin
resolves at start, so a missing grant fails the boot with the secret named.
A tenant admin grants the secret when the plugin is deployed.

Examples:
  gibson component init my-agent --kind agent
  gibson component init my-scanner --kind tool
  gibson component init my-plugin --kind plugin --with-secret cred:api_key
  gibson component init my-plugin --kind plugin --dir ~/projects --force
  gibson component init gitlab --kind connector

Flags

FlagTypeDefaultDescription
-d, --dirstring—destination directory (default: current directory)
--forcebool—overwrite existing files
--kindstring—component kind: agent | tool | plugin | connector (required)
--with-secretstringArray—plugin-only: a broker secret the plugin resolves at start, e.g. cred:api_key (repeatable)

gibson component run

Run the compiled component binary, supervising its signals

run starts the compiled component binary in this directory, forwards
its stdout/stderr to the operator's terminal, hooks SIGINT/SIGTERM, and
waits up to --drain-timeout (default 30s) for graceful shutdown before
escalating to SIGKILL.

run is a thin process supervisor — it does NOT compile the binary
(use `make build` first) and it does NOT mock handlers. The
component's existing graceful-drain logic in plugin.Serve / serve.Agent /
serve.Tool is the contract; this verb just supervises it.

--kind is required. It used to be auto-detected from component.yaml, which
no longer exists (ADR-0097). The binary is <dir>/<dir-name>, which is what
the scaffold's Makefile produces.

Pre-flight: refuses to launch if the runtime credential at
~/.gibson/<kind>/<name>.runtime.json is missing, and points at the two
environment variables that enrol a component at boot.

Exit codes are surfaced verbatim from the child.

Examples:
  gibson component run --kind tool
  gibson component run --kind plugin --dir ./my-plugin
  gibson component run --kind agent --drain-timeout 60s

Flags

FlagTypeDefaultDescription
-d, --dirstring.component directory (containing the compiled binary)
--drain-timeoutduration30smax wait between SIGTERM and SIGKILL on shutdown
--kindstring—component kind: agent | tool | plugin (required)

gibson component validate

Local schema + proto checks against a component directory

validate runs kind-aware local checks against the component in --dir
(default: current directory).

--kind is required. It used to be auto-detected from component.yaml, which
no longer exists (ADR-0097): the kind is the only thing a component
directory cannot imply, so it is the one thing you still state.

  agent:  main.go is present and parses
  tool:   agent checks, plus proto field 100 = DiscoveryResult, plus
          buf lint when buf is on PATH
  plugin: Go source of package main at the root, and each file parses;
          the plugin declares itself in code (ADR-0097)

Paths come from the directory rather than from a manifest: main.go at the
root, and the tool proto at
api/proto/gibson/tools/<name>/v1/<name>.proto, with <name> the directory
name minus hyphens.

Exit codes:
  0  no errors
  2  validation errors (one or more findings printed to stderr)
  1  I/O / setup error (e.g. --kind missing, or an unusable directory name)

Examples:
  gibson component validate --kind tool
  gibson component validate --kind plugin --dir ./my-plugin

Flags

FlagTypeDefaultDescription
-d, --dirstring.component directory
--kindstring—component kind: agent | tool | plugin (required)

gibson connector

Manage tenant connectors (ConnectorService)

gibson connector — enable and manage connectors via
ConnectorService on the Gibson daemon (ADR-0114 Slice 4). Pick a connector
from the curated catalog and it becomes a running connector the operator
reconciles onto ToolHive. You do not write YAML. Authenticated as you: run `gibson login` first.

Subcommands:
  catalog  list the curated connectors this tenant may enable
  enable   enable a connector from the catalog by its catalog id
  list     list the tenant's enabled connectors and their live status
  disable  disable an enabled connector (removes the running connector)

gibson connector catalog

List the curated connectors this tenant may enable

Call ConnectorService.ListCatalog and print the curated
connectors this tenant may enable. The set is the shipped catalog, filtered
by the per-tenant catalog gate. Enable one with `gibson connector enable <id>`.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRPC deadline

gibson connector disable

Disable an enabled connector

Call ConnectorService.DisableConnector to disable an enabled
connector by its id. The operator cascade-removes the running connector, its
network policy, and its credential secret. This action is destructive: it
asks you to confirm unless you pass --yes.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRPC deadline
--yesbool—Do not ask to confirm the disable

gibson connector enable

Enable a connector from the catalog

Call ConnectorService.EnableConnector for a catalog entry
(for example `gibson connector enable gitlab`). The daemon creates
the connector in your tenant and the operator reconciles it onto ToolHive.
An OAuth connector comes up in the AuthorizationRequired phase until a person
authorizes it. The enabled connector id and its initial phase are printed.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRPC deadline

gibson connector list

List the tenant's enabled connectors and their live status

Call ConnectorService.ListConnectors and print the tenant's
enabled connectors with their live status: shape, runtime, lifecycle phase,
the count of discovered tools, and the last error (if any).

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRPC deadline

gibson docs

Emit machine-readable docs

docs — emit developer-facing reference material.

Subcommands:
  cli       the command tree as machine-readable JSON (drives the CLI reference)

gibson docs cli

Emit the command tree as machine-readable JSON

cli walks the whole gibson command tree and writes it to stdout as a
stable JSON document (sorted, deterministic). It is the source of truth
for the auto-generated CLI reference in the documentation site: the
generator renders the reference from this JSON, and a drift gate fails
if the committed page no longer matches.

Regenerate the committed spec after any command, flag, or help-text
change:

  gibson docs cli > cli-spec.json

gibson init

Initialize a Gibson workspace (writes .gibson/workspace.yaml)

init writes a workspace.yaml that pins GIBSON_URL for this workspace,
so subsequent `gibson component <verb>` calls do not require
the flag every time.

By default the file is written to ./.gibson/workspace.yaml (per-project).
Pass --global to write to ~/.gibson/workspace.yaml (machine-wide
fallback).

The workspace file is non-secret. It MUST NOT contain client_id /
client_secret / bootstrap_token / host_key / password / secret / token
fields — Load() rejects them at parse time. Credentials live at
~/.gibson/{agent,tool,plugin}/credentials with mode 0600. Tenant
context is embedded in those credentials, so workspace.yaml carries
no tenant pin.

Examples:
  gibson init --gibson-url https://api.zeroroot.ai
  gibson init --global --gibson-url https://api.zeroroot.ai
  gibson init --force --gibson-url ...   # overwrite existing

Flags

FlagTypeDefaultDescription
--commentstring—Optional free-form note.
--forcebool—Overwrite an existing workspace file.
--gibson-urlstring—Gibson platform URL (e.g. https://api.zeroroot.ai). Required.
--globalbool—Write to ~/.gibson/workspace.yaml instead of ./.gibson/workspace.yaml.

gibson inspect

Show what this principal can do (calls WhoAmI on the Gibson daemon)

inspect loads the local runtime credential at
~/.gibson/<kind>/<name>.runtime.json (written by the component itself on
its first start, from GIBSON_URL and GIBSON_BOOTSTRAP_TOKEN), signs a per-RPC Capability-Grant JWT with the registered
agent key, and calls IdentityService.WhoAmI to print the principal's
effective Gibson permissions.

Auto-detection: when --kind is unset, inspect scans ~/.gibson/{agent,
tool,plugin}/*.runtime.json and, when exactly one exists, picks that.
Multiple installs require --kind (and --name). GIBSON_AGENT_KEY (a
base64 runtime credential) overrides the on-disk lookup for CI / k8s.

When no component credential exists and you ran gibson login, inspect
calls WhoAmI with your login session instead.

Output formats:
  default  human-friendly tree with stable action labels for grep
  --json   raw WhoAmIResponse as canonical proto-JSON (for scripts)

Flags

FlagTypeDefaultDescription
--jsonbool—Emit raw WhoAmIResponse JSON instead of the tree
--kindstring—agent | tool | plugin (auto-detected when only one exists)
--namestring—Install name when multiple of the same kind exist

gibson login

Authenticate the CLI against the Gibson platform (device flow)

login runs the OAuth 2.0 Device Authorization Grant against the
platform's identity service: it prints a URL + short code, you approve
in a browser, and the CLI stores the resulting session at
~/.gibson/auth/credentials (mode 0600). Every subsequent gibson command
then acts as you. The session refreshes silently; run gibson logout to
end it.

The CLI learns its issuer + public client_id from the platform
(GET {GIBSON_URL}/.well-known/gibson-login); pass --issuer/--client-id to
override for local or air-gapped setups. GIBSON_URL defaults to
https://api.zeroroot.ai; --gibson-url, the GIBSON_URL env var, or a
workspace file (gibson init) override it.

Flags

FlagTypeDefaultDescription
--client-idstring—Override the CLI OAuth client_id (skips platform bootstrap).
--gibson-urlstring—Gibson platform URL; falls back to GIBSON_URL, then the workspace, then https://api.zeroroot.ai.
--issuerstring—Override the OIDC issuer (skips platform bootstrap).
--no-browserbool—Do not attempt to open a browser; just print the URL.
--tenantstring—Assert the tenant you expect to sign in as; checked against your account, not selected by this flag.
--timeoutduration10m0sOverall deadline for the login flow.

gibson logout

End the CLI session and remove stored credentials

gibson mission

Author, validate, render, and submit gibson missions

gibson mission — author missions in CUE / YAML / JSON
and submit them to the daemon.

Subcommands:
  new       scaffold a new mission (--from-template <name> | minimal)
  validate  run cue vet / proto validation against an input file
  render    compile the input to proto-shaped JSON or YAML
  submit    validate + define + run via the daemon (full CUE→define→run)

gibson mission catalog

List the missions the platform ships, or show one

The platform's own mission definitions, compiled into the daemon.

With no arguments, list them with the parameters each one declares.
With a name, print that mission's CUE — the source the daemon renders,
not a summary of it.

Submit one with:

    gibson mission submit --catalog <name> --target <target-id> --param k=v

The parameter set is closed: an unknown key is refused rather than
dropped, so a typo cannot read as a value that bound.
gibson mission catalog list

List the missions the platform ships

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRequest deadline
gibson mission catalog show

Print a shipped mission's CUE, or its rendered definition

Print the mission's CUE source, verbatim, so what the daemon will
run can be read rather than trusted.

With --rendered, print the rendered MissionDefinition as JSON instead.
That needs every parameter the mission declares, because rendering is
what validates them.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--paramstringArray—A parameter, as key=value. Repeatable. Required with --rendered, because rendering is what validates them
--renderedbool—Print the rendered MissionDefinition as JSON instead of the mission's CUE
--timeoutduration30sRequest deadline

gibson mission new

Scaffold a new mission file

Scaffold a new mission file.

With --from-template <name>, writes the named template's content. Use
--list-templates to see available templates. Without flags, writes a
minimal scaffold with FIXME placeholders.

The scaffold names a target, so what it writes submits as written. Pass
--target <name-or-uuid> to choose one; with no --target the command reads
your tenant's targets and uses the only one, or asks you to pick when there
is more than one. A UUID is taken as given and needs no daemon.

Pass --no-target to scaffold offline. The file then carries an empty
target_ref, and submit refuses it until you fill it in or pass --target.

Flags

FlagTypeDefaultDescription
--from-templatestring—Name of a built-in template to scaffold from
--gibson-urlstring—Daemon URL (default: your login session's)
--list-templatesbool—List available templates and exit
--no-targetbool—Scaffold offline, leaving target_ref empty
-o, --outputstring-Output path; '-' for stdout
--targetstring—Target name or UUID to write into the scaffold
--timeoutduration30sTimeout for the target lookup

gibson mission render

Compile a mission file to proto-shaped JSON or YAML

Render the input mission file as the canonical proto-shaped JSON
the daemon expects. With --out-format yaml, JSON is converted to YAML
via sigs.k8s.io/yaml (round-trip-equivalent).

Useful for:
- Reviewing what the daemon will see before submitting.
- Diffing two mission files semantically (compile both then diff JSON).
- Piping into other tooling (`gibson mission render m.cue | jq …`).

Output is deterministic: protojson controls proto field ordering (camelCase,
stable); encoding/json.Indent normalizes whitespace, eliminating the
binary-hash-seeded extra space that protojson's internal detrand inserts
after colons to make builds non-reproducible.

Flags

FlagTypeDefaultDescription
--formatstring—Override input format detection: cue|yaml|json
--out-formatstringjsonOutput format: json|yaml

gibson mission submit

Validate, define, and run a mission via the daemon

Full CUE/YAML/JSON → define → run submit:

1. Load the mission. Either from a FILE (CUE / YAML / JSON detected
   from the extension or --format), or from the platform's own
   catalog with --catalog <name> --param k=v, which renders it
   server-side.
2. Run protovalidate on the parsed *missionv1.MissionDefinition.
3. With --dry-run, print the rendered JSON and exit; otherwise:
4. Call DaemonService/CreateMissionDefinition to register the
   definition and obtain a mission_definition_id.
5. Call DaemonService/CreateMission with the definition ID.
6. Print the returned mission ID.

A catalog mission is rendered by the daemon from the definition
compiled into its own binary (ADR-0118), so the graph is the
checked-in one rather than a copy. Its parameters are a closed set:
run `gibson mission catalog list` to see what each one
declares. A catalog mission declares no target, so --target is
required for it.

The daemon URL is taken from your login session (run `gibson login`
first); override it with --gibson-url. Production use should
route through the dashboard's Server Action path — this command
is the CLI escape hatch for development and CI.

Auth: the call is made over the authenticated login session
(bearer token only; the daemon resolves your tenant from your
account, not from this command); there is no plaintext or
unauthenticated path.

Flags

FlagTypeDefaultDescription
--catalogstring—Run a mission from the platform's catalog by name instead of from a file (list them with: gibson mission catalog list)
--detachbool—Return once the daemon has started the run and print the mission id; do not wait for the mission to finish
--dry-runbool—Print rendered JSON; do not contact the daemon
--formatstring—Override input format detection: cue|yaml|json
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--paramstringArray—A --catalog mission's parameter, as key=value. Repeatable. The set is closed: an unknown key is refused
--targetstring—Target id to bind the mission to (overrides the definition's target_ref)
--timeoutduration30sSubmit deadline

gibson mission validate

Validate a mission file (CUE / YAML / JSON)

Validate a mission file.

Steps:
1. Read and parse the file (CUE → JSON via cuelang; YAML → JSON via
   sigs.k8s.io/yaml; JSON passes through). Format detected from the
   file extension; override with --format.
2. Unmarshal into *missionv1.MissionDefinition via protojson.
3. Run protovalidate against the message — every
   (buf.validate.field).* annotation declared in the SDK protos
   is enforced here, matching what the daemon applies at submit
   time.
4. Check that target_ref, when set, is a target UUID. The daemon
   rejects any other value.
5. Check that each starts_from names an earlier node: a node that
   exists, is not the node itself, and is an ancestor of the node
   through dependencies or edges (ADR-0169). The daemon applies the
   same rule at submit time.

Exits non-zero with the underlying library's error message on any
failure. Use '-' as the file path to read from stdin.

Flags

FlagTypeDefaultDescription
--formatstring—Override format detection: cue|yaml|json

gibson secret

Store, list, rotate, and delete tenant secrets

gibson secret — manage the credentials your components use.

A secret is a NAME and BYTES. There is no type or format field: the thing that
reads a credential is the only party that knows what it needs, so it validates
by parsing (ADR-0096).

NAMES ARE EXACT. The name you give is the stored key, and it is also the
additional authenticated data of the secret's own envelope, so a name that
differs by one character is a different secret and a mistyped one is
unrecoverable. Nothing here trims or rewrites what you type.

Every name begins with a namespace:

  cred:<name>                         a credential a component uses
  provider_config:<provider>:<field>  an LLM provider setting

`gibson secret list` prints exact keys, which are exactly what goes into a
mission's credential_names.

Subcommands:
  set      store a secret, from a file or stdin
  get      show one secret's metadata (never its value)
  list     list secret names and metadata (never values)
  rotate   store a new value for an existing secret
  delete   remove a secret
  count    how many secrets the active backend holds
  backend  show or configure which backend stores the secrets

gibson secret backend

Show or configure which backend stores the secrets

gibson secret backend — which store the tenant's secrets live in.

Two backends exist. Every other provider was retired and its enum value
reserved, so there is no AWS, GCP or Azure option to choose:

  hosted  the platform-managed OpenBao, isolated per tenant by namespace.
          Zero configuration, and already active.
  byo     your own Vault or OpenBao, isolated by path prefix because OSS
          Vault and OpenBao CE have no namespaces.

Subcommands:
  show   print the active configuration, with sensitive fields redacted
  probe  validate a candidate configuration WITHOUT saving it
  set    probe a candidate configuration and save it on success
gibson secret backend probe

Validate a candidate configuration without saving it

Check that a candidate backend configuration works, and change nothing.

Run this before `set`. A backend that cannot be reached and is saved anyway
leaves every secret unreadable until it is fixed.

Flags

FlagTypeDefaultDescription
--addressstring—Vault/OpenBao address (byo)
--approle-role-idstring—AppRole role id (auth-method approle)
--approle-secret-id-filestring—File holding the AppRole secret id (auth-method approle)
--auth-methodstring—token or approle (byo)
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--mountstring—KV mount (byo)
--path-prefixstring—Path prefix that isolates this tenant (byo)
--providerstring—hosted or byo
--timeoutduration30sRequest deadline
--token-filestring—File holding the Vault token (auth-method token)
gibson secret backend set

Probe a candidate configuration and save it on success

Save a backend configuration, after the server probes it.

The server probes before it persists, so a configuration that cannot be reached
is refused rather than stored.

Flags

FlagTypeDefaultDescription
--addressstring—Vault/OpenBao address (byo)
--approle-role-idstring—AppRole role id (auth-method approle)
--approle-secret-id-filestring—File holding the AppRole secret id (auth-method approle)
--auth-methodstring—token or approle (byo)
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--mountstring—KV mount (byo)
--path-prefixstring—Path prefix that isolates this tenant (byo)
--providerstring—hosted or byo
--timeoutduration30sRequest deadline
--token-filestring—File holding the Vault token (auth-method token)
gibson secret backend show

Print the active backend configuration, redacted

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRequest deadline

gibson secret count

How many secrets the active backend holds

Count the secrets in the tenant's active backend.

This asks the backend rather than the metadata index, so it is the check for
whether a backend swap moved everything it should have.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRequest deadline

gibson secret delete

Remove a secret

Remove a secret.

A job whose credential_names still declares this name will fail to resolve it
once it is gone, so check with `gibson secret get` before deleting a name you did
not create.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRequest deadline
--yesbool—Confirm the deletion

gibson secret get

Show one secret's metadata (never its value)

Show a secret's metadata.

This never prints the value, and not because the CLI withholds it: the RPC does
not return it. The only RPC in Gibson that returns a plaintext credential is the
harness callback a sandboxed component uses, which is not callable from here.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRequest deadline

gibson secret list

List secret names and metadata (never values)

List the tenant's secrets.

The names printed are exact stored keys, which is what a mission's
credential_names needs, so they can be copied without translation.

  gibson secret list
  gibson secret list --prefix cred:

When more secrets exist than one page holds, the command prints the token
of the next page. Pass it to --page-token to read that page.

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--page-sizeint32—Maximum number to return (0 = server default)
--page-tokenstring—Token of the page to read, from the previous page
--prefixstring—Only names beginning with this prefix (e.g. cred:)
--timeoutduration30sRequest deadline

gibson secret rotate

Store a new value for an existing secret

Store a new value under an existing name, creating a new version.

Rotation keeps the name, which matters: the name is what a job's
credential_names declares, so rotating a credential needs no change anywhere
else.

Flags

FlagTypeDefaultDescription
--from-filestring—Read the value from this file
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--stdinbool—Read the value from stdin
--timeoutduration30sRequest deadline

gibson secret set

Store a secret, from a file or stdin

Store a secret under an exact name.

The name is the stored key and the envelope's AAD, so it is used verbatim —
nothing is trimmed. The namespace prefix determines the category; there is no
--category flag, because a category that disagreed with the prefix would write
a key nobody can read.

  gibson secret set cred:goat-cluster --from-file ~/.kube/goat.yaml
  kubectl config view --raw | gibson secret set cred:goat-cluster --stdin

Flags

FlagTypeDefaultDescription
--from-filestring—Read the value from this file
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--stdinbool—Read the value from stdin
--timeoutduration30sRequest deadline

gibson target

Create, list, inspect, update, and delete assessment targets

gibson target — manage the systems your missions assess.

A target is identified by a server-minted UUID; the name and other fields are
metadata. Missions reference a target by its UUID — names are never resolved.

Subcommands:
  create  register a new target (prints the minted UUID)
  list    list your targets (UUID + metadata)
  get     show a single target by UUID
  update  replace a target's metadata by UUID
  delete  remove a target by UUID

gibson target create

Register a new target and print its minted UUID

Flags

FlagTypeDefaultDescription
--descriptionstring—Free-text description
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--namestring—Human-readable target name (metadata)
--providerstring—Backing provider (e.g. openai)
--tagstringSlice—Tag (repeatable)
--target-timeoutint32—Per-operation timeout in seconds
--timeoutduration30sRequest deadline
--typestring—Target type (e.g. llm_chat, custom)
--urlstring—Target endpoint URL

gibson target delete

Remove a target by UUID

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRequest deadline

gibson target get

Show a single target by UUID

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--timeoutduration30sRequest deadline

gibson target list

List your targets (UUID + metadata)

Flags

FlagTypeDefaultDescription
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--page-sizeint32—Max results (0 = server default)
--page-tokenstring—Token of the page to read, from the previous page
--providerstring—Filter by provider
--statusstring—Filter by status
--tagstringSlice—Filter by tag (repeatable; target must carry all)
--timeoutduration30sRequest deadline
--typestring—Filter by type

gibson target update

Replace a target's metadata by UUID

Flags

FlagTypeDefaultDescription
--descriptionstring—Free-text description
--gibson-urlstring—Override the daemon URL (defaults to the login session).
--namestring—Human-readable target name (metadata)
--providerstring—Backing provider
--tagstringSlice—Tag (repeatable)
--target-timeoutint32—Per-operation timeout in seconds
--timeoutduration30sRequest deadline
--typestring—Target type
--urlstring—Target endpoint URL

On this page