Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

observal registry

Publish and manage registry components. The registry has five component types: MCP servers, skills, hooks, prompts, and sandboxes.

Subcommand structure

observal registry <type> <action> [args]
Type
Submit
List
My
Show
Install
Render
Edit

mcp

yes

yes

yes

yes

yes

no

yes

skill

yes

yes

yes

yes

yes

no

yes

hook

yes

yes

no

yes

yes

no

yes

prompt

yes

yes

yes

yes

no

yes

yes

sandbox

yes

yes

no

yes

no

no

yes

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.

Shared lifecycle and collaboration commands

observal registry skill archive alice/reviewer --yes --output json
observal registry skill unarchive alice/reviewer --yes --output json
observal registry skill transfer-owner alice/reviewer bob --yes --output json
observal registry skill co-authors list alice/reviewer --output json
observal registry skill co-authors add alice/reviewer bob@example.com --output json
observal registry skill co-authors remove alice/reviewer <user-uuid> --output json

Archive, restore, and ownership transfer require explicit confirmation in JSON mode. Their JSON output is the direct server result. Co-author list returns the standard list envelope; add and remove return the direct server result.

The namespace is the publisher's username or a teamspace handle. Usernames cannot change after the account owns a registry listing. Team members can browse approved private teamspace items in normal list results. Use --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:

The file is a bare array or an object with a components array. Each entry contains type plus the normal API submission fields:

Dry run validates file structure without contacting submission endpoints. Execution structurally validates every entry before the first mutation, submits entries in order, reports conflicts as skipped, and returns per-entry IDs, canonical names, review status, and safe errors. 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

Option
Short
Description

--git

-g

Analyze a git repository instead of pasting config

--name

-n

Pre-fill server name (skip prompt)

--category

-c

Pre-fill category (skip prompt)

--yes

-y

Accept all defaults

--draft

Save as draft instead of submitting for review

--submit

Submit an existing draft for review (MCP ID)

--output

-o

Output format: table or json

Default flow (JSON paste)

  1. Prompts you to paste your MCP server JSON config.

  2. 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": [...]}

  3. Auto-detects environment variables from $VAR patterns and env keys.

  4. Shows a config preview and prompts for metadata (name, description, category).

  5. Submits to registry for review.

Git analysis flow (--git)

  1. Shallow-clones the repo.

  2. Detects the MCP framework (FastMCP, MCP SDK, TypeScript SDK, Go SDK).

  3. Extracts server name, description, and exposed tools via AST.

  4. Scans for required env vars (os.environ, os.getenv, .env.example, server.json).

  5. Prompts for metadata confirmation.

  6. 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.

Option
Short
Description

--search

-s

Search by name or description

--category

-c

Filter by category

--limit

-n

Max results (default: 50)

--sort

Sort by: name, category, version

--output

-o

Output format: table, json

--interactive

-i

Open a fuzzy-search picker

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. Prompts for required environment variables and headers unless non-interactive or machine output is selected.

Option
Short
Description

--harness

-i

Target harness (required)

--version

-V

Generate configuration for one version

--env

-e

Environment value as KEY=VALUE; repeatable

--header

Header value as KEY=VALUE; repeatable

--env-file

Read environment values from a file

--no-prompt

-y

Use supplied values and placeholders without prompting

--raw

Output only the bare config snippet for piping

--output

-o

Output the complete operation result as table or JSON

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.

Option
Short
Description

--from-file

-f

Load updates from a JSON file

--name

-n

New listing name

--description

-d

New description

--category

-c

New category

--version

-v

New version string

--git-url

New git URL

--command

New command

--url

New URL (SSE/HTTP)

--bump

Version bump for approved listings: patch, minor, or major

--changelog

Changelog for an approved-listing version

--output

-o

Output format: table or json

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.

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.

Option
Short
Description

--from-file

-f

Create from JSON file

--skill-md

Path to SKILL.md (auto-fills fields from frontmatter)

--git-url

Git repository URL

--git-ref

Branch or tag (default: main)

--draft

Save as draft instead of submitting for review

--submit

Submit a draft for review (skill ID)

--output

-o

Output format: table or json

observal registry skill list

List approved skills in the registry.

Option
Short
Description

--task-type

-t

Filter by task type

--target-agent

Filter by target agent

--search

-s

Search by name or description

--output

-o

Output format: table, json

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.

Option
Short
Description

--harness

-i

Target harness (required)

--scope

-s

Install scope: user (global, default) or project

--raw

Output raw JSON only

--no-write

Generate config without writing skill files or lockfile state

--version

-V

Install one version instead of the latest

--output

-o

Output the operation result as table or JSON

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.

JSON output does not disable installation. It returns whether files were written and the installed path. Raw and no-write modes do not record the skill as installed. 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.

Option
Short
Description

--from-file

-f

Load updates from JSON file

--name

-n

New listing name

--description

-d

New description

--version

-v

New version string

--task-type

-t

New task type

--git-url

New git URL

--git-ref

New git ref

--output

-o

Output format: table or json

observal registry hook submit

Submit a new hook for review. Supports inline script content via --script, or git-hosted hooks via --source-url.

Option
Short
Description

--from-file

-f

Create from JSON file

--draft

Save as draft instead of submitting for review

--submit

Submit a draft for review (hook ID)

--script

Path to hook script file (content stored in registry)

--source-url

Git repo containing hook scripts

--source-ref

Branch/tag to track (default: main)

--source-path

Directory within repo containing hook files

--requires

Install prerequisites (repeatable)

--output

-o

Output format: table or json

observal registry hook list

List approved hooks from the registry.

Option
Short
Description

--event

-e

Filter by event type

--search

-s

Search by name or description

--output

-o

Output format: table, json

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.

Option
Short
Description

--harness

-i

Target harness (required)

--platform

-p

Platform: win32, darwin, linux

--raw

Output raw JSON only (no file writes)

--dir

-d

Project directory for file writes (default: cwd)

--output

-o

Output the complete installation result as table or JSON

Hook installation validates every path before writing, refuses to replace malformed existing JSON, writes files atomically, and does not duplicate an existing event entry when repeated.

observal registry hook edit

Edit a draft, pending, or rejected hook submission. Acquires an edit lock to prevent concurrent modifications.

Option
Short
Description

--from-file

-f

Load updates from JSON file

--name

-n

New listing name

--description

-d

New description

--version

-v

New version string

--event

-e

New event type

--output

-o

Output format: table or json

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.

Option
Short
Description

--from-file

-f

Create from JSON file, or read template from a text file

--draft

Save as draft instead of submitting for review

--submit

Submit a draft for review (prompt ID)

--output

-o

Output format: table or json

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.

Option
Short
Description

--category

-c

Filter by category

--search

-s

Search by name or description

--output

-o

Output format: table, json

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.

Option
Short
Description

--var

-v

Variable as key=value (repeatable)

--output

-o

Output format: table or json

observal registry prompt edit

Edit a draft, pending, or rejected prompt submission. Acquires an edit lock to prevent concurrent modifications.

Option
Short
Description

--from-file

-f

Load updates from JSON file

--name

-n

New listing name

--description

-d

New description

--version

-v

New version string

--category

-c

New category

--template

-t

New template text

--output

-o

Output format: table or json

observal registry sandbox submit

Submit a new sandbox environment for review.

Option
Short
Description

--from-file

-f

Create from JSON file

--draft

Save as draft instead of submitting for review

--submit

Submit a draft for review (sandbox ID)

--output

-o

Output format: table or json

observal registry sandbox list

List approved sandboxes in the registry.

Option
Short
Description

--runtime

-r

Filter by runtime type

--search

-s

Search by name or description

--output

-o

Output format: table, json

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.

Option
Short
Description

--from-file

-f

Load updates from JSON file

--name

-n

New listing name

--description

-d

New description

--version

-v

New version string

--runtime-type

-r

New runtime type

--image

-i

New container image

--output

-o

Output format: table or json

Component versions

Use observal 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

Use observal 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.

Previousobserval agent pull
Nextobserval registry recommend

Last updated

Was this helpful?