Subcommand structure
Every component type also supports archive, unarchive, ownership transfer, and co-author management. Registry also contains the
models, version, recommend, and mixed bulk groups.
All registry references accept a UUID, canonical namespace/slug, a unique legacy bare name, a row number from the latest human list output for the same component type, or an @alias. Agents and scripts must use returned UUIDs or qualified_name values, never row numbers. If the same bare slug exists in multiple namespaces, qualify it, for example alice/search instead of search.
Fork an approved component
fork commands accept SOURCE [--name NAME] [--version BASE] [--new-version V] [--team HANDLE|UUID] [--visibility public|team] [--output table|json]. Only currently approved sources and approved base versions are eligible. The fork is a separate editable draft, not a new release of the original; it has its own namespace, owner, reviews, and installation identity. Team-private sources can only be forked within their teamspace. JSON returns the direct server draft object. Edit using observal registry <type> edit FORK_UUID ... and submit through that type’s draft workflow. show prints visible fork provenance and the count of public approved direct forks. If source access is lost, it displays Source unavailable rather than the saved source reference. A private or unpublished fork never increases the public count.
Shared lifecycle and collaboration commands
--team TEAM_HANDLE to include public items plus that team’s private items, or --namespace TEAM_HANDLE to restrict results to that namespace. Direct references use team-handle/item-slug. Nonmembers receive the same not-found response for private items as for unknown items.
Teamspace visibility
Use the teamspace target and visibility options on submit commands:public teamspace items are visible to all registry users. team items are visible only to team members and privileged reviewers. Team owners and reviewers can change visibility after publication. A team member’s new submission still follows the normal review workflow.
Mixed bulk submission
Submit up to 200 MCP, skill, hook, prompt, and sandbox entries from one JSON file:components array. Each entry contains type plus the normal API submission fields:
partial; item errors set it to true and exit with code 11, while conflicts counted as skips remain successful. Authentication, permission, rate-limit, version, and service failures stop the batch. JSON execution requires --yes.
Re-running a partially completed file is safe only after inspecting results. Existing identities are skipped for component types that reject duplicates. Verify created items by returned UUID or qualified_name.
MCP servers
MCP server registry commands for submitting, browsing, generating configuration, editing, and archiving MCP server listings.observal registry mcp submit
Submit an MCP server to the registry. By default, paste your server’s JSON config (the same format you use in your harness). Use --git to analyze a git repository instead.
Synopsis
Options
Default flow (JSON paste)
- Prompts you to paste your MCP server JSON config.
- Accepts multiple formats:
- harness config:
{"mcpServers": {"name": {"command": "...", "args": [...], "env": {...}}}} - Bare config:
{"command": "npx", "args": ["-y", "pkg"]} - SSE/HTTP:
{"url": "http://...", "type": "sse", "headers": {...}} - server.json manifest:
{"packages": [...], "remotes": [...]}
- harness config:
- Auto-detects environment variables from
$VARpatterns andenvkeys. - Shows a config preview and prompts for metadata (name, description, category).
- Submits to registry for review.
Git analysis flow (--git)
- Shallow-clones the repo.
- Detects the MCP framework (FastMCP, MCP SDK, TypeScript SDK, Go SDK).
- Extracts server name, description, and exposed tools via AST.
- Scans for required env vars (
os.environ,os.getenv,.env.example,server.json). - Prompts for metadata confirmation.
- Submits to registry for review.
Examples
Valid categories
browser-automation, cloud-platforms, code-execution, communication, databases, developer-tools, devops, file-systems, finance, knowledge-memory, monitoring, multimedia, productivity, search, security, version-control, ai-ml, data-analytics, general.
Valid transports
stdio, sse, streamable-http.
Valid frameworks
python, docker, typescript, go.
observal registry mcp list
List approved MCP servers in the registry.
observal registry mcp my
List your own MCP servers across all statuses (draft, pending, approved, rejected).
observal registry mcp show
Show full details of an MCP server including validation results, env vars, and supported harnesses.
observal registry mcp install
Generate a harness config snippet for an MCP server. This command does not write harness configuration or record an installation. Interactive mode prompts for required environment variables and headers. JSON mode requires --no-prompt and rejects missing required values before config generation with error.result.needs_input: true.
observal registry mcp edit
Edit an MCP server submission. For draft/pending/rejected listings, edits in place. For approved listings, publishes a new version with a semver bump.
Without flags, opens an interactive JSON paste prompt (same format as submit).
observal registry mcp transfer-owner
Transfer ownership to another username. You stop being the owner immediately.
observal registry mcp sync
Publish a new MCP version automatically when the listing’s GitHub or GitLab repository changes. See Sync an MCP server from GitHub or GitLab for the full setup.
On an existing setup,
enable keeps any setting you do not pass.
Skills
Skill registry commands. Skills are portable SKILL.md instruction packages that provide agents with task-specific guidance. Valid task types:code-review, code-generation, testing, documentation, debugging, refactoring, deployment, security-audit, performance, general.
observal registry skill submit
Submit a new skill for review. Provide --git-url to let the server fetch SKILL.md automatically, or use --skill-md to paste content directly.
observal registry skill list
List approved skills in the registry.
observal registry skill my
List your own skills across all statuses (draft, pending, approved, rejected).
observal registry skill show
Show detailed information about a skill, including validation status, task type, git source, and slash command.
observal registry skill install
Install a skill by fetching the full skill directory from git. Clones the skill directory via sparse checkout and writes it to the appropriate harness skill path.
Scopes:
user(default): writes to~/.<harness>/skills/<name>/globally.project: writes to.agents/skills/<name>/in the current directory, then symlinks into detected harness config directories.
--version. A failed file write or lockfile update returns a categorized failure instead of reporting success.
observal registry skill edit
Edit a draft, pending, or rejected skill submission. Acquires an edit lock to prevent concurrent modifications.
observal registry hook submit
Submit a new hook for review. Supports inline script content via --script, or git-hosted hooks via --source-url.
observal registry hook list
List approved hooks from the registry.
observal registry hook show
Show detailed information for a single hook, including event type, handler config, and execution mode.
observal registry hook install
Install a hook for a specific harness. Writes script files and merges hook config into the harness’s settings. Existing hooks are preserved during merge.
observal registry hook edit
Edit a draft, pending, or rejected hook submission. Acquires an edit lock to prevent concurrent modifications.
observal registry prompt submit
Submit a new prompt template for review. You can submit interactively, from a JSON file, or from a raw template file.
If
--from-file points to a non-JSON file, its content is used as the template and you are prompted for metadata interactively.
observal registry prompt list
List approved prompts in the registry.
observal registry prompt my
List your own prompts across all statuses (draft, pending, approved, rejected).
observal registry prompt show
Show detailed information about a prompt, including the template content.
observal registry prompt render
Render a prompt template with variable substitution. Sends key=value pairs to the server, which substitutes them into the template and returns the rendered output.
observal registry prompt edit
Edit a draft, pending, or rejected prompt submission. Acquires an edit lock to prevent concurrent modifications.
observal registry sandbox submit
Submit a new sandbox environment for review.
observal registry sandbox list
List approved sandboxes in the registry.
observal registry sandbox show
Show detailed information about a sandbox, including runtime type, container image, and resource limits.
Sandboxes are attached to agents by UUID and are installed when the agent is pulled. There is no standalone Sandbox install command.
observal registry sandbox edit
Edit a draft, pending, or rejected sandbox submission. Acquires an edit lock to prevent concurrent modifications.
Component versions
Useobserval registry version publish and observal registry version list for all five component types. Publication supports direct JSON results; history supports explicit pagination.
See observal registry version for the complete contract.
Personalized recommendations
Useobserval registry recommend to rank visible components against the signed-in user’s sessions and to dismiss or mark recommendations as installed.
See observal registry recommend for the JSON schema and feedback actions.
