Recipe Registry

Publish and pull recipes from local or remote registries

Recipe Registry CLI

The recipe registry allows you to publish, pull, and manage recipes in a centralized location.

Quick Start

# Publish a recipe to local registry
praisonai recipe publish ./my-recipe

# Pull a recipe from registry
praisonai recipe pull my-recipe@1.0.0

# List recipes in registry
praisonai recipe list

Commands

publish

Publish a recipe bundle or directory to the registry.

praisonai recipe publish <bundle-or-directory> [options]

Options:

Option	Description
--registry <path-or-url>	Registry path or URL (default: ~/.praisonai/registry)
--token <token>	Authentication token for remote registry
--force	Overwrite existing version
--json	Output JSON format

Examples:

# Publish a bundle
praisonai recipe publish my-recipe-1.0.0.praison

# Publish a directory (auto-packs)
praisonai recipe publish ./my-recipe

# Publish to custom registry
praisonai recipe publish ./my-recipe --registry /path/to/registry

# Force overwrite existing version
praisonai recipe publish ./my-recipe --force

# JSON output
praisonai recipe publish ./my-recipe --json

pull

Pull a recipe from the registry.

praisonai recipe pull <name>[@version] [options]

Options:

Option	Description
--registry <path-or-url>	Registry path or URL
--token <token>	Authentication token
-o, --output <dir>	Output directory (default: current)
--json	Output JSON format

Examples:

# Pull latest version
praisonai recipe pull my-recipe

# Pull specific version
praisonai recipe pull my-recipe@1.0.0

# Pull to specific directory
praisonai recipe pull my-recipe -o ./recipes

# Pull from custom registry
praisonai recipe pull my-recipe --registry /path/to/registry

list

List every recipe in the local registry. This is registry-scoped and differs from praisonai recipe list — recipe list reads per-recipe metadata, while registry list enumerates the full registry with tag filtering.

praisonai registry list [options]

Options:

Option	Type	Default	Description
--dir <path>	string	~/.praison/registry	Registry directory
--tags <a,b>	comma-separated	None	Filter recipes by tags (any-match)
--json	flag	false	Output in JSON format

Examples:

# List all local recipes
praisonai registry list

# Filter by tags (matches audio OR video)
praisonai registry list --tags audio,video

# JSON output
praisonai registry list --json

rich is a soft dependency. Without it, list prints one line per recipe ({name} ({version}): {description}). An empty registry prints No recipes found in registry: <path> and exits 0.

For remote-registry listing, use praisonai recipe list --registry http://… instead — registry list only reads the local --dir.

Registry Types

Local Registry

The default registry is stored at ~/.praisonai/registry. No configuration required.

# Uses default local registry
praisonai recipe publish ./my-recipe
praisonai recipe pull my-recipe

Custom Local Registry

Specify a custom path for the registry:

# Use custom path
praisonai recipe publish ./my-recipe --registry /shared/recipes
praisonai recipe pull my-recipe --registry /shared/recipes

HTTP Registry

Start a local HTTP registry server and connect to it:

# Start HTTP registry server
praisonai serve registry --port 7777

# Start with authentication required
praisonai serve registry --port 7777 --token mysecret

# Start in read-only mode
praisonai serve registry --port 7777 --read-only

Connect to HTTP registry:

# Publish to HTTP registry
praisonai recipe publish ./my-recipe --registry http://localhost:7777

# Publish with token authentication
praisonai recipe publish ./my-recipe \
  --registry http://localhost:7777 \
  --token $PRAISONAI_REGISTRY_TOKEN

# Pull from HTTP registry
praisonai recipe pull my-recipe --registry http://localhost:7777

# List recipes from HTTP registry
praisonai recipe list --registry http://localhost:7777

# Search HTTP registry
praisonai recipe search agent --registry http://localhost:7777

Remote HTTPS Registry

Connect to remote registries:

# Publish to remote registry
praisonai recipe publish ./my-recipe \
  --registry https://registry.example.com \
  --token $REGISTRY_TOKEN

# Pull from remote registry
praisonai recipe pull my-recipe \
  --registry https://registry.example.com

Registry Server Commands

serve

Start a local HTTP registry server.

praisonai registry serve is deprecated and will be removed in a future version. Use praisonai serve registry instead — both accept the same flags and default to port 7777. See the Recipe Registry Server guide for the canonical form. The deprecated form prints this warning to stderr:

⚠ DEPRECATION WARNING:
'praisonai registry serve' is deprecated and will be removed in a future version.
Please use 'praisonai serve registry' instead.

praisonai serve registry [options]

Options:

Option	Description
--host <addr>	Host to bind to (default: 127.0.0.1)
--port <port>	Port to bind to (default: 7777)
--dir <path>	Registry directory (default: ~/.praisonai/registry)
--token <token>	Require token for write operations
--read-only	Disable all write operations
--json	Output in JSON format

Examples:

# Start on default port
praisonai serve registry

# Start on custom port
praisonai serve registry --port 8080

# Start with authentication
praisonai serve registry --token mysecrettoken

# Start with custom directory
praisonai serve registry --dir /path/to/registry

# Start in read-only mode (no publish/delete)
praisonai serve registry --read-only

status

Check registry server health.

praisonai registry status [options]

Options:

Option	Description
--registry <url>	Registry URL (default: http://localhost:7777)
--json	Output in JSON format

Examples:

# Check default registry
praisonai registry status

# Check specific registry
praisonai registry status --registry http://localhost:8080

# JSON output
praisonai registry status --json

To enumerate recipes in the local registry, use the list command above.

HTTP API Endpoints

When running praisonai serve registry, the following endpoints are available:

Method	Endpoint	Description
GET	/healthz	Health check
GET	/v1/recipes	List all recipes
GET	/v1/recipes/{name}	Get recipe info
GET	/v1/recipes/{name}/{version}	Get version info
GET	/v1/recipes/{name}/{version}/download	Download bundle
POST	/v1/recipes/{name}/{version}	Publish bundle (auth required)
DELETE	/v1/recipes/{name}/{version}	Delete version (auth required)
GET	/v1/search?q=...	Search recipes

Registry Structure

~/.praisonai/registry/
├── index.json           # Recipe index
└── recipes/
    └── my-recipe/
        └── 1.0.0/
            ├── manifest.json
            └── my-recipe-1.0.0.praison

Environment Variables

Variable	Description
PRAISONAI_REGISTRY_TOKEN	Default authentication token

Exit Codes

Code	Meaning
0	Success
2	Validation error (invalid bundle)
7	Recipe not found

Python API

from praisonai.recipe.registry import LocalRegistry, get_registry

# Create registry
registry = LocalRegistry()  # Uses default path
# or
registry = LocalRegistry("/custom/path")

# Publish
result = registry.publish("my-recipe-1.0.0.praison")
print(f"Published: {result['name']}@{result['version']}")

# Pull
result = registry.pull("my-recipe", version="1.0.0", output_dir="./recipes")
print(f"Pulled to: {result['path']}")

# List
recipes = registry.list_recipes()
for r in recipes:
    print(f"{r['name']} ({r['version']})")

# Search
results = registry.search("hello")

Next Steps

• Run History - Store and export run history
• Security Features - SBOM, signing, auditing
• Policy Packs - Manage tool permissions