Skip to main content
Find approved registry resources for the task at hand and use them in the current session, without building an Agent first. Discovery searches every kind at once (agents, MCP servers, skills, hooks, prompts, sandboxes), ranks by relevance, and tells you separately whether each result is approved, whether it works in your harness, and whether it can be used right now or only after a restart. For signed-in users, results are scoped to personal listings they own and listings in every teamspace they currently belong to (including public teamspace listings); other people’s public listings are not returned. Global reviewers and admins retain their review/admin scope. Anonymous public discovery is unchanged when the public registry is enabled. The bundled observal skill tells coding assistants to run this before reinventing something or declaring a capability unavailable.
Pass the task as one shell-escaped argument (single-quote it and escape any embedded ' as '\''). Several bare words are still joined into one query, but the text comes from the user and must never be spliced into a shell command unquoted. JSON returns query, harness, count, and results[]. Important result fields: An empty results array is a successful answer: nothing matched. Try fewer or different words before concluding the resource does not exist.

​
Inspect

Returns the complete entry, including representativeQueries (what the resource is good for), capabilities, the versioned artifact url, and its digest. The predecessor urn:ai: prefix is accepted.

​
Use

What happens depends on the kind:
  • Skills and prompts are text. The exact approved version is fetched from its permanent URL and printed (JSON: content, activated: true, mode: context). The use is recorded in the capability lock.
  • MCP servers, agents, sandboxes, and hooks change your setup. Nothing is written; the response carries next_step, the existing install command (observal registry mcp install …, observal agent pull …), which confirms before touching harness config and takes effect after a restart. JSON: activated: false, mode: next-session.
Unapproved resources are refused without --yes. A resource whose obs:supportedHarnesses excludes the detected harness is refused; pass --harness to override the detection.

​
The capability lock

Every activation appends one line to ~/.observal/capability_lock.jsonl: timestamp, harness, working directory, identifier, kind, version, digest, and mode. agent pull and the component install commands append too. Session upload (session_push hooks and observal reconcile) attaches the lines that fall inside a session’s harness, directory, and time window as capabilities_used, which is how Observal knows which resources a session relied on. Nothing secret is stored. Entries older than 30 days are pruned. Related: observal agent init --from-capabilities turns the resources used in a directory into a draft Agent.

​
Exit codes

Follows the shared CLI error contract: 4 permission (unapproved resource without --yes), 5 not found, 7 validation (unknown type, harness, or identifier).