Item Registry

The genie install, genie publish, and genie item commands manage the Genie item registry. Items are reusable components distributed via git repositories and described by a genie.yaml manifest.

Item Types

Type	Description
`agent`	Autonomous agent with model config, roles, and entrypoint
`skill`	Reusable skill with triggers and entrypoint
`app`	Application with runtime, NATS prefix, and entrypoint
`board`	Board definition with stage pipeline and gate configs
`workflow`	Scheduled workflow with cron expression and command
`stack`	Bundle of multiple items installed together
`template`	Project template for scaffolding
`hook`	Hook script triggered by lifecycle events

`genie install`

Install a Genie item from a git repository.

genie install <target> [options]

The target is a git URL with an optional version tag:

github.com/user/repo
github.com/user/repo@v1.0.0
https://github.com/user/repo.git@v2.0.0
git@github.com:user/repo.git

Option	Description
`--force`	Override existing item with same name
`--full`	Full git clone instead of shallow

What happens on install

Clones the repository (shallow by default) to ~/.genie/items/<name>/
Detects the manifest — genie.yaml, or inferred from AGENTS.md, manifest.ts, skill.md
Validates the manifest against type-specific rules
Registers the item in the app store (PostgreSQL)
Runs type-specific setup:
- agent — regenerates agent cache
- board — creates task type with stage pipeline
- workflow — registers schedule with cron expression
- stack — recursively installs all bundled items

--force overwrites an existing item with the same name. If you made local edits inside ~/.genie/items/<name>/, they’re discarded — use --full during development so the clone is a full git checkout you can work from.

Install a stack to bootstrap an entire workspace in one command — stack items recursively install every agent, skill, board, and workflow they bundle.

Examples

# Install an agent
genie install github.com/automagik-dev/agent-reviewer

# Install a specific version
genie install github.com/automagik-dev/board-software@v1.2.0

# Force reinstall
genie install github.com/automagik-dev/agent-reviewer --force

# Full clone (for development)
genie install github.com/automagik-dev/my-stack --full

`genie publish`

Publish the current directory as a Genie item. Must be run from a directory containing a valid manifest. Requires a pushed git tag matching the manifest version.

genie publish

Prerequisites

A genie.yaml manifest (or detectable convention) in the current directory
A git tag matching the manifest version (e.g., v1.0.0 for version 1.0.0)
The tag must be pushed to the remote

What happens on publish

Detects and validates the manifest in the current directory
Verifies a git tag matching v<version> exists and is pushed to the remote
Registers or updates the item in the app store
Records the version in app_versions with git SHA
Sets approval status to pending

Example

# Tag and publish
git tag v1.0.0
git push origin v1.0.0
genie publish

genie publish records the version in app_versions against a specific git SHA — once registered, that (name, version) pair cannot be quietly replaced. If you pushed a broken tag, bump the version and publish again rather than trying to rewrite history.

`genie item update`

Update an installed item to the latest version or a specific tag.

genie item update [name] [options]

Option	Description
`--all`	Update all git-installed items

# Update a specific item
genie item update my-agent

# Update all installed items
genie item update --all

`genie item uninstall`

Remove an installed item.

genie item uninstall <name>

genie item uninstall my-agent

Manifest Format

Every item is described by a genie.yaml manifest:

name: my-agent
type: agent
version: 1.0.0
description: A review agent
author:
  name: automagik
  url: https://github.com/automagik-dev
tags: [review, code-quality]
category: development
license: MIT
dependencies:
  - some-other-item

agent:
  model: sonnet
  entrypoint: AGENTS.md
  roles: [reviewer, qa]

Required Fields

Field	Description
`name`	Item name (used as identifier)
`type`	One of: `agent`, `skill`, `app`, `board`, `workflow`, `stack`, `template`, `hook`
`version`	Semantic version string

Type-Specific Sections

Each type has its own section with type-specific fields: agent

agent:
  model: sonnet
  entrypoint: AGENTS.md
  roles: [engineer, reviewer]

skill

skill:
  triggers: ["/review", "review this"]
  entrypoint: skill.md

board

board:
  stages:
    - name: draft
      gate: human
    - name: build
      gate: agent
      auto_advance: true
    - name: review
      gate: human+agent

workflow

workflow:
  cron: "0 9 * * 1-5"
  timezone: America/Sao_Paulo
  command: genie spawn reporter

stack

stack:
  items:
    - name: my-board
      type: board
      inline: true
      config:
        stages:
          - name: todo
            gate: human
    - name: my-agent
      type: agent
      source: github.com/user/agent-repo

Manifest Detection

If no genie.yaml exists, Genie infers the manifest from conventions:

File	Inferred type
`genie.yaml`	Explicit manifest (first priority)
`AGENTS.md`	`agent` — reads name, model, roles from YAML frontmatter
`manifest.ts`	`app`
`skill.md`	`skill`

Boards

Boards are one of the item types you can publish and install.

Scheduling

Workflow items create schedules on install.

Database

Inspect the app store tables that back the registry.

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Item Registry

Item Registry

Item Types

`genie install`

What happens on install

Examples

`genie publish`

Prerequisites

What happens on publish

Example

`genie item update`

`genie item uninstall`

Manifest Format

Required Fields

Type-Specific Sections

Manifest Detection

See also

Directory

Boards

Scheduling

Database

​Item Registry

​Item Types

​genie install

​What happens on install

​Examples

​genie publish

​Prerequisites

​What happens on publish

​Example

​genie item update

​genie item uninstall

​Manifest Format

​Required Fields

​Type-Specific Sections

​Manifest Detection

​See also

Directory

Boards

Scheduling

Database

Item Registry

Item Types

`genie install`

What happens on install

Examples

`genie publish`

Prerequisites

What happens on publish

Example

`genie item update`

`genie item uninstall`

Manifest Format

Required Fields

Type-Specific Sections

Manifest Detection

See also