human prompts

Manage HUMΛN prompts as first-class, versioned artifacts — list what's in the registry, validate local files, preview renders, publish new versions, and roll back when something regresses.

Delegation-gated commands (list, versions, publish, rollback, deprecate) require a profile with the matching prompt:* scopes. Local commands (lint, render, cost) run against files on disk and do not call the API.

Subcommands

Subcommand	Description	Auth
`list`	List prompts you can read	`prompt:read`
`versions <key>`	Version history for one prompt	`prompt:read`
`lint`	Validate local prompt files	Local only
`render <key>`	Preview rendered prompt with variables	Local only
`cost <key>`	Estimate token cost for a prompt	Local only
`publish <key>`	Publish a prompt version to the registry	`prompt:publish:{key}`
`rollback <key>`	Roll back to a previous version	`prompt:rollback:{key}`
`deprecate <key>`	Mark a version deprecated	`prompt:deprecate:{key}`

human prompts list

List prompts visible to your current delegation.

Option	Description
`--namespace <namespace>`	Filter by namespace (e.g. `companion.task`)
`--scope <scope>`	Filter by scope: `core`, `org`, `marketplace`
`--format <format>`	Output format: `table` (default) or `json`

human prompts list
# Prompts (12):
#   • legal.contract-analysis v1.2.0 [org]
#   • companion.task.summarize v3.0.1 [core]

human prompts list --namespace companion.task --scope org --format json

human prompts versions

Show semver history for a single prompt key.

Argument	Description
`<key>`	Prompt key (e.g. `legal.contract-analysis`)

human prompts versions legal.contract-analysis
# Versions of legal.contract-analysis:
#   1.2.0 (current) - 2026-05-01T14:22:00.000Z
#   1.1.0 - 2026-04-12T09:00:00.000Z

human prompts lint

Validate all prompt files under a directory (YAML frontmatter, inputSchema vs {{variables}}).

Option	Description
`--dir <dir>`	Prompts directory (default: `./prompts`)

human prompts lint --dir ./prompts
# Linting 4 prompt(s)...
#   ✓ core/agents/summarize/system
#   ✗ org/legal/contract-analysis — ERROR: missing version in meta
# 4 prompts, 1 error(s), 0 warning(s)
# Exit code 1 when errors exist

human prompts render

Preview a prompt after variable substitution (reads from disk, no API).

Argument / option	Description
`<key>`	Prompt id to render
`--var <key=value>`	Repeat for each template variable
`--dir <dir>`	Prompts directory (default: `./prompts`)

human prompts render core/agents/summarize/system \
  --var topic="Q2 revenue" \
  --var audience="executive"
# --- core/agents/summarize/system v1.0.0 (core/canon) ---
# You summarize {{topic}} for {{audience}} ...

human prompts cost

Estimate token usage and per-call cost for a prompt file.

Argument / option	Description
`<key>`	Prompt id
`--model <model>`	Model for estimation (default: `gpt-4o`)
`--dir <dir>`	Prompts directory (default: `./prompts`)

human prompts cost core/agents/summarize/system --model gpt-4o
# Token Cost Estimate:
#   Prompt:  core/agents/summarize/system
#   Model:   gpt-4o
#   Tokens:  ~842
#   Cost:    ~$0.002106/call

human prompts publish

Publish the active local prompt to the registry. Requires prompt:publish:{key} on your delegation.

Argument / option	Description
`<key>`	Prompt id to publish (must exist under `--dir`)
`--scope <scope>`	Publication scope: `org` (default) or `marketplace`
`--dir <dir>`	Prompts directory (default: `./prompts`)

Reads version, content, and meta from the local prompt file, then POSTs the full body the API expects.

human prompts lint --dir ./prompts
human prompts publish legal.contract-analysis --scope org
# ✔ Published: prompt://org/legal.contract-analysis@1.3.0

Maps to POST /v1/prompts/:key/publish with body { version, content, meta, input_schema? }. System prompts must include the Prompt Defense Baseline markers (see human prompts lint). The MCP tool human.prompts.publish accepts the same fields.

human prompts rollback

Point the active version at a previous semver. Requires prompt:rollback:{key}.

Argument / option	Description
`<key>`	Prompt key
`--to <version>`	Required. Target semver (e.g. `1.0.0`)

human prompts rollback legal.contract-analysis --to 1.0.0
# ✔ Rolled back legal.contract-analysis to 1.0.0

Maps to POST /v1/prompts/:key/rollback with body { target_version }.

human prompts deprecate

Mark a specific version deprecated without deleting history. Requires prompt:deprecate:{key}.

Argument / option	Description
`<key>`	Prompt key
`--version <version>`	Required. Version to deprecate

human prompts deprecate legal.contract-analysis --version 1.1.0
# ✔ Deprecated legal.contract-analysis v1.1.0

Examples

Complete dev-to-publish workflow with a safety rollback:

# 1. Validate local prompt files before you touch the registry
human prompts lint --dir ./prompts
# ✓ core/agents/support-triage/system

# 2. Preview with production variables
human prompts render core/agents/support-triage/system \
  --var product="Acme Cloud" \
  --var tier="enterprise"

# 3. Publish to your org scope
human prompts publish core/agents/support-triage/system --scope org
# ✔ Published: prompt://org/core/agents/support-triage/system@1.0.0

# 4. Confirm version history
human prompts versions core/agents/support-triage/system
#   1.0.0 (current) - 2026-05-19T10:00:00.000Z

# 5. Ship 1.1.0, discover a regression in staging
human prompts publish core/agents/support-triage/system --scope org
# ✔ Published: ...@1.1.0

# 6. Roll back active pointer — 1.1.0 remains in history, no longer active
human prompts rollback core/agents/support-triage/system --to 1.0.0
# ✔ Rolled back core/agents/support-triage/system to 1.0.0