ALPACALOOP(1)

NAME
alpacaloop - AlpacaLoop command line interface

SYNOPSIS
alpaca [command] [options]
alpaca docs [list|show <topic-id|docs-path>|search <query>]
alpaca help --all

DESCRIPTION
AlpacaLoop is a provider-neutral issue and pull request control plane for AI workers. It connects repository work, tracker issues, worker configuration, workflow templates, and pull request publication.

Most users start with repository setup, create or inspect managed issues, then choose either a foreground run or the background service.

QUICK START
alpaca init
alpaca auth setup  # for codex/claude workers
alpaca doctor
alpaca issue create --prompt "Fix flaky login tests."
alpaca run --issue 123
alpaca service enable
alpaca service status
alpaca issue list --days 7 --limit 10
alpaca service log show --tail 50

On Linux and WSL2, service enable requires a working systemd user session (systemctl --user). WSL2 support assumes systemd is enabled; otherwise keep using run for foreground cycles.

COMMANDS

  Setup and health

alpaca init
    Create or update alpaca.config.json, register repo/tracker settings, tune service limits, language, and worker run caps, then resolve missing sign-in requirements.

alpaca auth setup
    Start interactive Codex and Claude worker sign-in setup, covering browser, device-code, CLI, stored API key, and environment fallback flows.

alpaca auth list
    Show machine-local worker auth profiles, provider coverage, invalid or cooled-down entries, and rotation readiness without changing sign-ins.

alpaca doctor
    Audit local setup readiness by checking config, worker binaries, auth profiles, cooldowns, managed labels, repository registration, and service state.

alpaca docs
    List, read, open, or search packaged AlpacaLoop concept docs; use command help for option syntax and docs for conceptual behavior.

alpaca labels sync
    Create or reconcile the configured AlpacaLoop-managed labels in the tracker for the current repository.

  Daily issue work

alpaca issue create
    Create an AlpacaLoop-managed issue from worker-drafted prompt input or manual title/body input, with optional workflow overrides and reviewed drafts.

alpaca issue list
    List tracker issues for triage with state, age, label, assignee, compact/detailed, markdown/text, or browser filters.

alpaca issue show
    Show one AlpacaLoop-managed issue with workflow status, parent/source chain, related children, PR details, and relevant comments.

alpaca run
    Process runnable workflow issues once in the foreground, optionally restricted by issue id; use for manual runs, not while the service is active.

alpaca service enable
    Install and start the AlpacaLoop background polling service so it watches registered repositories for runnable work.

alpaca service status
    Show background service state, registered repositories, active work, and whether the service is installed or running.

alpaca service log show
    Show machine-local background service logs, with optional tailing for recent polling and worker-launch diagnostics.

  Publishing and collaboration

alpaca publish
    Publish selected local changes by committing, pushing, opening a pull request, and merging to the base branch unless reviewers or --no-merge are requested.

alpaca issue followup
    Create or dry-run an independent post-completion follow-up issue from an existing issue, carrying an optional request prompt and workflow selector for later follow-up execution.

alpaca issue broadcast
    Post or dry-run one shared tracker comment to explicit issue ids or filtered open AlpacaLoop queue issues.

alpaca issue unlock
    Request release of AI: Running ownership for one or more issues so they can return to AI: Ready after the worker stops or ownership expires.

  Workflow and skill authoring

alpaca workflow create
    Draft reusable workflow template decisions from prompt/template-set input, or create one from manual body/scaffold, with optional required skills/MCP and reviewed drafts.

alpaca workflow update
    Update a fixed workflow template from a prompt, or use template-set mode for related create/update/reuse changes with reviewed draft application.

alpaca workflow delete
    Delete one repo-local workflow template, blocking when references remain unless a reviewed cleanup draft is saved and applied.

alpaca workflow lint
    Validate one or all workflow templates locally, including structure, nested references, section order, and required capability availability.

alpaca workflow list
    List workflow templates or references to one template, optionally including system templates and printing text or JSON output.

alpaca event-hook config
    Configure machine-local publish event hook settings, including the user-scoped hook file directory used by user hooks.

alpaca event-hook add
    Register an existing repo-scoped or user-scoped publish event hook file for selected triggers, one repo or all repos as allowed.

alpaca event-hook create
    Ask a worker to create a repo or user publish event hook file from a prompt, then register it or save/apply a reviewed draft.

alpaca event-hook update
    Ask a worker to update an already registered repo or user publish event hook file from a prompt, or save/apply a reviewed draft.

alpaca event-hook list
    List configured repo and/or user publish event hooks for one repository or all registered repositories.

alpaca event-hook remove
    Remove a repo-scoped or user-scoped publish event hook registration by path without deleting unrelated hook files.

alpaca event-hook test
    Run one publish event hook with sample completed-event JSON to test its runner and observe any real side effects.

alpaca capability list
    List installed skill and MCP capabilities as JSON, hiding refs excluded from workflow requires by default.

alpaca capability search
    Search installed, catalog-backed, discovery-only, and provider candidates across skill and MCP sources as JSON.

alpaca skill list
    List installed worker skills as JSON, including whether each ref is usable in workflow requires.skills for a configured worker.

alpaca skill search
    Search installed skills, repo/system catalog entries, and provider marketplaces as JSON, optionally asking a worker to rank matches.

alpaca skill install
    Install a selected file, GitHub, Claude plugin, or Codex plugin skill candidate for one worker runtime, then print install results as JSON.

alpaca skill create
    Create a skill-resolution tracker issue, or save/apply reviewed draft JSON, without writing SKILL.md directly.

alpaca skill catalog list
    List repo-visible installable skill catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.

alpaca skill catalog add
    Add or replace one repo-local user skill catalog entry with worker-specific or default install sources.

alpaca skill catalog import-github
    Import every SKILL.md under a GitHub repository directory as repo-local installable skill catalog entries for selected worker runtimes.

alpaca skill catalog remove
    Remove one repo-local user skill catalog entry by id; packaged or ejected system entries are not removed.

alpaca mcp list
    List MCP servers visible to worker runtimes as JSON, including diagnostics about usable server and tool refs.

alpaca mcp search
    Search installed MCP servers and catalog entries as JSON, optionally asking a worker to rank matches.

alpaca mcp install
    Install one safe catalog-backed MCP server into a worker runtime.

alpaca mcp create
    Create an MCP-resolution tracker issue, or save/apply reviewed draft JSON, without editing MCP catalog or worker config directly.

alpaca mcp verify
    Verify configured MCP server or tool refs against configured workers before declaring workflow requires.mcp.

alpaca mcp catalog list
    List repo-visible MCP install catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.

alpaca mcp catalog add
    Add or replace one repo-local MCP catalog entry from a JSON object read from a file or stdin.

alpaca mcp catalog remove
    Remove one repo-local MCP catalog entry by id; packaged or ejected system entries are not removed.

  Maintenance and recovery

alpaca cleanup
    Remove machine-local AlpacaLoop service state by default, or clean eligible closed-issue worker workspaces when --workspaces is supplied.

alpaca detach
    Unregister a repository from service management; with --purge, delete managed files, repo-local .alpaca assets, and workspaces after confirmation.

alpaca auth clear
    Remove machine-local worker auth profiles by provider, invalid-only, or all profiles, with confirmation unless -y or --yes is supplied.

alpaca state patch
    Preview or apply canonical workflow state comment schema migrations across selected issues, writing backups before non-dry-run updates.

alpaca state restore
    Restore canonical workflow state comments from a JSONL backup, with dry-run and hash-safety controls for targeted recovery.

alpaca eject
    Copy packaged workflow, system-prompt, or catalog assets into .alpaca for repository-local editing, overwriting only with --force.

alpaca service disable
    Stop and remove the background polling service after current service work finishes, or immediately with --force.

alpaca service restart
    Restart the background polling service after current service work finishes so it reloads configuration or package updates.

RUN MODES

alpaca run
    Processes runnable workflow issues once in the foreground. Use this for manual control, targeted issue runs, or local debugging.

alpaca service enable
    Installs and starts the background polling service. Use this when AlpacaLoop should keep watching for runnable work.

Choose one run mode at a time. Stop the service with service disable before using run.

SAFETY NOTES

•   publish finalizes local changes by committing them, opening a pull request, and merging it into the base branch unless reviewers are requested. Review the selected paths, message, and reviewers before confirming.

•   detach without --purge only unregisters the repository. detach --purge can delete managed repository files and workspaces after confirmation.

•   cleanup removes machine-local state or eligible workspaces after confirmation in an interactive terminal.

•   auth clear removes machine-local built-in worker sign-ins. Use --for, --invalid, or --all to keep the scope explicit.

•   service disable --force and service restart --force stop or restart without waiting for current service work to finish.

•   state patch and state restore update canonical workflow state comments. Use state patch --dry-run --state open to check open issue migration before publishing workflow state schema or patch changes.

EXAMPLES
alpaca init --repo-provider github
alpaca issue create --prompt "Investigate queue delay" --save-draft
alpaca issue create --apply-draft ~/.alpaca/drafts/.../issue-create-....json
alpaca issue show --issue 123 --children 1 --limit 5
alpaca issue search --title "memory" --state all --limit 10
alpaca issue broadcast --open --message-file message.txt --dry-run
alpaca workflow lint
alpaca skill search browser --for codex
alpaca mcp search github --for lmstudio-coder
alpaca service disable

FILES

alpaca.config.json
    Repository-local AlpacaLoop configuration created or updated by init.

.alpaca/workflows/
    Repository-local workflow templates. Ejected packaged workflows live under .alpaca/workflows/__system/.

.alpaca/system-prompts/
    Repository-local optional system prompt guidance ejected for editing.

.alpaca/catalog/
    Repository-local skill and MCP catalog entries.

skills/alpaca/references/
    Packaged AlpacaLoop reference docs used by the docs command.

~/.alpaca/
    Machine-local AlpacaLoop state, including auth profile metadata, drafts, and logs under ~/.alpaca/logs/ unless evidenceRoot routes logs elsewhere.

HELP
alpaca --help
alpaca help --all
alpaca <command> --help
alpaca docs
alpaca docs list
alpaca docs show config
alpaca docs search <query>

COMMAND REFERENCE
The following reference is generated from the same help topics used by the CLI.
alpaca <command>
Commands:
  init                         Create or update alpaca.config.json, register repo/tracker settings, tune service limits, language, and worker run caps, then resolve missing sign-in requirements.
  doctor                       Audit local setup readiness by checking config, worker binaries, auth profiles, cooldowns, managed labels, repository registration, and service state.
  docs                         List, read, open, or search packaged AlpacaLoop concept docs; use command help for option syntax and docs for conceptual behavior.
  eject                        Copy packaged workflow, system-prompt, or catalog assets into .alpaca for repository-local editing, overwriting only with --force.
  auth setup                   Start interactive Codex and Claude worker sign-in setup, covering browser, device-code, CLI, stored API key, and environment fallback flows.
  auth list                    Show machine-local worker auth profiles, provider coverage, invalid or cooled-down entries, and rotation readiness without changing sign-ins.
  auth order                   Show the built-in worker authentication preference order AlpacaLoop will try when selecting Codex or Claude profiles for issue runs.
  auth clear                   Remove machine-local worker auth profiles by provider, invalid-only, or all profiles, with confirmation unless -y or --yes is supplied.
  detach                       Unregister a repository from service management; with --purge, delete managed files, repo-local .alpaca assets, and workspaces after confirmation.
  cleanup                      Remove machine-local AlpacaLoop service state by default, or clean eligible closed-issue worker workspaces when --workspaces is supplied.
  run                          Process runnable workflow issues once in the foreground, optionally restricted by issue id; use for manual runs, not while the service is active.
  publish                      Publish selected local changes by committing, pushing, opening a pull request, and merging to the base branch unless reviewers or --no-merge are requested.
  issue approve                Post `/alpaca approve` to one AlpacaLoop-managed issue as its assignee; the next service scan records the approval.
  issue start                  Post `/alpaca start` to one issue waiting for start approval as its assignee; the next service scan records the approval.
  issue disable                Add the disabled workflow rule to one or more open issues without changing their workflow status.
  issue enable                 Remove the disabled workflow rule from one or more open issues without changing their workflow status.
  issue create                 Create an AlpacaLoop-managed issue from worker-drafted prompt input or manual title/body input, with optional workflow overrides and reviewed drafts.
  issue followup               Create or dry-run an independent post-completion follow-up issue from an existing issue, carrying an optional request prompt and workflow selector for later follow-up execution.
  issue list                   List tracker issues for triage with state, age, label, assignee, compact/detailed, markdown/text, or browser filters.
  issue search                 Search tracker issues by title or portable provider-backed text query without loading comments, dependencies, or workflow details.
  issue show                   Show one AlpacaLoop-managed issue with workflow status, parent/source chain, related children, PR details, and relevant comments.
  issue broadcast              Post or dry-run one shared tracker comment to explicit issue ids or filtered open AlpacaLoop queue issues.
  issue log list               List machine-local issue run log files captured from worker executions for later inspection or debugging.
  issue log show               Show machine-local worker logs for one issue, with optional tailing to inspect recent execution output.
  issue log search             Search machine-local issue run logs for text and optionally include surrounding context lines.
  issue unlock                 Request release of AI: Running ownership for one or more issues so they can return to AI: Ready after the worker stops or ownership expires.
  state patch                  Preview or apply canonical workflow state comment schema migrations across selected issues, writing backups before non-dry-run updates.
  state restore                Restore canonical workflow state comments from a JSONL backup, with dry-run and hash-safety controls for targeted recovery.
  labels sync                  Create or reconcile the configured AlpacaLoop-managed labels in the tracker for the current repository.
  catalog topics list          Print shared skill and MCP catalog topic metadata as JSON, combining active system topics with repo-local user topics.
  capability list              List installed skill and MCP capabilities as JSON, hiding refs excluded from workflow requires by default.
  capability search            Search installed, catalog-backed, discovery-only, and provider candidates across skill and MCP sources as JSON.
  skill list                   List installed worker skills as JSON, including whether each ref is usable in workflow requires.skills for a configured worker.
  skill search                 Search installed skills, repo/system catalog entries, and provider marketplaces as JSON, optionally asking a worker to rank matches.
  skill install                Install a selected file, GitHub, Claude plugin, or Codex plugin skill candidate for one worker runtime, then print install results as JSON.
  skill create                 Create a skill-resolution tracker issue, or save/apply reviewed draft JSON, without writing SKILL.md directly.
  skill catalog list           List repo-visible installable skill catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.
  skill catalog add            Add or replace one repo-local user skill catalog entry with worker-specific or default install sources.
  skill catalog import-github  Import every SKILL.md under a GitHub repository directory as repo-local installable skill catalog entries for selected worker runtimes.
  skill catalog remove         Remove one repo-local user skill catalog entry by id; packaged or ejected system entries are not removed.
  mcp list                     List MCP servers visible to worker runtimes as JSON, including diagnostics about usable server and tool refs.
  mcp search                   Search installed MCP servers and catalog entries as JSON, optionally asking a worker to rank matches.
  mcp install                  Install one safe catalog-backed MCP server into a worker runtime.
  mcp create                   Create an MCP-resolution tracker issue, or save/apply reviewed draft JSON, without editing MCP catalog or worker config directly.
  mcp verify                   Verify configured MCP server or tool refs against configured workers before declaring workflow requires.mcp.
  mcp catalog list             List repo-visible MCP install catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.
  mcp catalog add              Add or replace one repo-local MCP catalog entry from a JSON object read from a file or stdin.
  mcp catalog remove           Remove one repo-local MCP catalog entry by id; packaged or ejected system entries are not removed.
  workflow create              Draft reusable workflow template decisions from prompt/template-set input, or create one from manual body/scaffold, with optional required skills/MCP and reviewed drafts.
  workflow update              Update a fixed workflow template from a prompt, or use template-set mode for related create/update/reuse changes with reviewed draft application.
  workflow delete              Delete one repo-local workflow template, blocking when references remain unless a reviewed cleanup draft is saved and applied.
  workflow lint                Validate one or all workflow templates locally, including structure, nested references, section order, and required capability availability.
  workflow list                List workflow templates or references to one template, optionally including system templates and printing text or JSON output.
  event-hook config            Configure machine-local publish event hook settings, including the user-scoped hook file directory used by user hooks.
  event-hook add               Register an existing repo-scoped or user-scoped publish event hook file for selected triggers, one repo or all repos as allowed.
  event-hook create            Ask a worker to create a repo or user publish event hook file from a prompt, then register it or save/apply a reviewed draft.
  event-hook update            Ask a worker to update an already registered repo or user publish event hook file from a prompt, or save/apply a reviewed draft.
  event-hook list              List configured repo and/or user publish event hooks for one repository or all registered repositories.
  event-hook remove            Remove a repo-scoped or user-scoped publish event hook registration by path without deleting unrelated hook files.
  event-hook test              Run one publish event hook with sample completed-event JSON to test its runner and observe any real side effects.
  service enable               Install and start the AlpacaLoop background polling service so it watches registered repositories for runnable work.
  service disable              Stop and remove the background polling service after current service work finishes, or immediately with --force.
  service restart              Restart the background polling service after current service work finishes so it reloads configuration or package updates.
  service status               Show background service state, registered repositories, active work, and whether the service is installed or running.
  service log show             Show machine-local background service logs, with optional tailing for recent polling and worker-launch diagnostics.
Notes:
  init creates or updates alpaca.config.json in the target repository.
  init may ask you to resolve service connections and set up a sign-in before it can finish.
  auth setup is interactive only. Codex sign-in supports browser, device-code, API key, and OPENAI_API_KEY fallback flows. Claude sign-in supports CLI, stored API key, and ANTHROPIC_API_KEY fallback flows.
  auth clear asks for confirmation unless you pass -y or --yes.
  labels sync reconciles tracker managed labels in the current repository.
  service enable runs AlpacaLoop in the background. Stop it with service disable before using run.
  service disable and service restart wait for current service work to finish and start no new service work while waiting. Use --force to perform the requested action immediately.
  AI: Running means ownership continuity across polls; it does not imply an actively executing worker at every moment.
  issue create uses --prompt for worker-drafted issues, or --title with exactly one of --body or --body-file for manual issues.
  skill create and mcp create ask workers to draft only the title and capability summary; the commands build final resolution issue bodies, and --apply-draft creates reviewed draft JSON without rerunning workers.
  workflow create uses --prompt to let the worker inspect the catalog and choose reuse/update/create, or --path for manual template creation.
  workflow create and workflow update manage reusable templates; issue create creates issues, and its help groups initial workflow options separately from issue creation options.
Use `alpaca <command> --help` for command-specific options. Use `alpaca docs` for concept docs. Use `alpaca help --all` for the full command reference.
---
Usage:
  alpaca init [--cwd <path>] [--create-repo] [--repo-provider <provider>] [--repo <project-ref>]
              [--remote-name <name>] [--base-branch <name>]
              [--tracker-provider <provider>] [--tracker <project-ref>]
              [--poll-interval <seconds>] [--max-workers <count>] [--max-issues <count>]
              [--parallelism-mode <balance|greedy>]
              [--max-ai-runs <count>] [--max-ai-hours <hours|off>] [--reviewer <name> ...]
  alpaca init [--language <en|ja|zh>] [--display-time-zone <IANA time zone>]
Create or update alpaca.config.json, register repo/tracker settings, tune service limits, language, and worker run caps, then resolve missing sign-in requirements.
Options:
  --cwd <path>: Repository directory to initialize or register. Relative paths are resolved from the current directory.
  --create-repo: Create the missing Gitea repository before writing local setup. Requires --repo-provider gitea.
  --repo-provider <provider>: Repository host provider such as github, gitlab, or gitea.
  --repo <project-ref>: Repository project reference. If omitted, AlpacaLoop tries to infer it from git remotes.
  --remote-name <name>: Git remote to use for repository discovery and branch operations.
  --base-branch <name>: Default branch for top-level workflow state and pull-request merge targets.
  --tracker-provider <provider>: Ticket tracker provider.
  --tracker <project-ref>: Ticket tracker project reference.
  --poll-interval <seconds>: Background service polling interval.
  --max-workers <count>: Maximum repo-wide AI worker slots.
  --max-issues <count>: Maximum active worker issues.
  --parallelism-mode <balance|greedy>: Worker slot allocation mode.
  --max-ai-runs <count>: Default maximum AI runs before human input is required.
  --max-ai-hours <hours|off>: Default maximum AI work hours before human input is required.
  --reviewer <name>: Add a default PR reviewer. Can be repeated.
  --language <en|ja|zh>: Default output language for CLI text, managed comments, and worker-generated human-facing text.
  --display-time-zone <IANA time zone>: Display and schedule input time zone.
Notes:
  Creates or updates alpaca.config.json in the target repository.
  May prompt interactively for missing repository, tracker, or sign-in settings.
  --create-repo is Gitea-only in this version; tracker provider and project must match the repository project.
  Existing remotes must already contain the configured base branch. New empty Gitea repos created by this command are seeded from local HEAD when possible.
Docs:
  alpaca docs show config
---
Usage:
  alpaca doctor
Audit local setup readiness by checking config, worker binaries, auth profiles, cooldowns, managed labels, repository registration, and service state.
Notes:
  Remote base branch checks are failures because managed issues and service workspaces cannot run without that branch.
Docs:
  alpaca docs show config
---
Usage:
  alpaca docs
  alpaca docs list [--with-description]
  alpaca docs show <topic-id|docs-path> [--web]
  alpaca docs search <query...> [--context <lines>] [--view matches|headings]
List, read, open, or search packaged AlpacaLoop concept docs; use command help for option syntax and docs for conceptual behavior.
Commands:
  list    List AlpacaLoop docs paths.
  show    Read one AlpacaLoop docs topic ID or docs path.
  search  Search AlpacaLoop docs topics.
Notes:
  Use docs for conceptual explanations such as alpaca.config.json behavior.
  Use <command> --help for command-specific options.
Use `alpaca docs list --help`, `alpaca docs show --help`, or `alpaca docs search --help` for docs command details.
---
Usage:
  alpaca docs list [--with-description]
List AlpacaLoop docs paths.
Options:
  --with-description: Include topic, title, description, and path.
---
Usage:
  alpaca docs show <topic-id|docs-path> [--web]
Read one AlpacaLoop docs topic ID or docs path.
Options:
  --web: Open the docs page in a browser.
Notes:
  Topic IDs are references-relative paths without .md, such as config or command-flows.
  Docs paths can be references/config.md or skills/alpaca/references/config.md.
---
Usage:
  alpaca docs search <query...> [--context <lines>] [--view matches|headings]
Search AlpacaLoop docs topics.
Options:
  --context <lines>: Include N context lines around matches. Ignored with --view headings. Default: 2.
  --view matches|headings: Choose match snippets or matching docs with heading outlines. Default: matches.
---
Usage:
  alpaca eject <workflows|system-prompts|catalog|all> [--force]
Copy packaged workflow, system-prompt, or catalog assets into .alpaca for repository-local editing, overwriting only with --force.
Options:
  --force: Overwrite existing ejected files with the packaged versions.
Notes:
  workflows writes packaged system workflows, including no_template default workflows, to .alpaca/workflows/__system/.
  system-prompts writes .alpaca/system-prompts/.
  catalog writes .alpaca/catalog/__system/{skill.json,mcp.json,metadata.json}.
  all ejects workflows first, then system prompts, then the catalog.
---
Usage:
  alpaca auth <setup|list|order|clear>
Manage machine-local worker authentication profiles.
Commands:
  setup  Start interactive Codex and Claude worker sign-in setup, covering browser, device-code, CLI, stored API key, and environment fallback flows.
  list   Show machine-local worker auth profiles, provider coverage, invalid or cooled-down entries, and rotation readiness without changing sign-ins.
  order  Show the built-in worker authentication preference order AlpacaLoop will try when selecting Codex or Claude profiles for issue runs.
  clear  Remove machine-local worker auth profiles by provider, invalid-only, or all profiles, with confirmation unless -y or --yes is supplied.
Notes:
  Use a subcommand help page for action-specific options.
Use `alpaca auth <command> --help` for command-specific options.
---
Usage:
  alpaca auth setup
Start interactive Codex and Claude worker sign-in setup, covering browser, device-code, CLI, stored API key, and environment fallback flows.
Notes:
  Interactive only. Codex sign-in supports browser, device-code, API key, and OPENAI_API_KEY fallback flows. Claude sign-in supports CLI, stored API key, and ANTHROPIC_API_KEY fallback flows.
  Custom workers do not use auth setup; configure their OpenAI-compatible endpoint and environment-variable secrets in alpaca.config.json.
---
Usage:
  alpaca auth list
Show machine-local worker auth profiles, provider coverage, invalid or cooled-down entries, and rotation readiness without changing sign-ins.
---
Usage:
  alpaca auth order
Show the built-in worker authentication preference order AlpacaLoop will try when selecting Codex or Claude profiles for issue runs.
---
Usage:
  alpaca auth clear [--all | [--for codex|claude] [--invalid]] [-y|--yes]
Remove machine-local worker auth profiles by provider, invalid-only, or all profiles, with confirmation unless -y or --yes is supplied.
Options:
  --all: Clear all auth profiles instead of the selected/default scope.
  --for codex|claude: Clear only sign-ins for one worker provider.
  --invalid: Clear only sign-ins already excluded from rotation by an auth error.
  -y, --yes: Skip the confirmation prompt.
Notes:
  Without -y or --yes, auth clear asks for confirmation.
---
Usage:
  alpaca detach [--cwd <path>] [--purge] [--force]
Unregister a repository from service management; with --purge, delete managed files, repo-local .alpaca assets, and workspaces after confirmation.
Options:
  --cwd <path>: Repository directory to detach. Relative paths are resolved from the current directory.
  --purge: Delete AlpacaLoop-managed repository files and workspaces after unregistering.
  --force: Purge managed files even when local contents differ from the packaged copy.
Notes:
  Without --purge, detach unregisters the repo but leaves local files in place.
  With --purge, detach asks for confirmation in an interactive terminal before unregistering and deleting managed files, repo-local .alpaca files, and the project workspace root.
  With --purge --force, the confirmation also calls out that modified managed files can be deleted.
  --force should only be used when local managed-file edits are disposable.
---
Usage:
  alpaca cleanup [--workspaces]
Remove machine-local AlpacaLoop service state by default, or clean eligible closed-issue worker workspaces when --workspaces is supplied.
Options:
  --workspaces: Clean eligible worker workspaces.
Notes:
  In an interactive terminal, cleanup asks for confirmation before removing local state or closed issue workspaces.
---
Usage:
  alpaca run [--issue <id[,id...]>]
Process runnable workflow issues once in the foreground, optionally restricted by issue id; use for manual runs, not while the service is active.
Options:
  --issue <id[,id...]>: Restrict the run to one or more tracker issue ids.
Notes:
  AI: Running means AlpacaLoop is running or has accepted a continuation; it does not guarantee an actively executing worker at every moment.
  Missing workflow templates, workflow template fit gaps, skills, or MCP servers may create blocking setup issues with localized Required Action checklists before launching a worker.
---
Usage:
  alpaca publish [--path <path> ...] [-m|--message <text>] [--reviewer <name[,name...]> ...] [--no-merge] [--restart-service] [-y|--yes]
Publish selected local changes by committing, pushing, opening a pull request, and merging to the base branch unless reviewers or --no-merge are requested.
Options:
  --path <path>: Commit only local changes under this repository-relative path. Repeat to include multiple paths. Existing unpublished commits on the branch are still pushed and included in the pull request.
  -m, --message <text>: Commit message and pull request title. Defaults to a short publish message.
  --reviewer <name[,name...]>: Request pull request review from one or more users. Repeat or use comma-separated names. When set, publish leaves the pull request unmerged.
  --no-merge: Leave the pull request unmerged after committing, pushing, and opening or reusing it.
  --restart-service: Usually unnecessary; safely restart the background service after publishing when the running service must reload an AlpacaLoop package update.
  -y, --yes: Skip the confirmation prompt.
Notes:
  Publishes the current repository working tree explicitly; the background service never runs this command automatically.
  Publish assigns the pull request to the authenticated tracker user while preserving existing assignees.
  When creating a pull request, publish asks a configured worker to draft the pull request body from the changes and falls back to a fixed publish note when no worker can do so.
  Ignored files are not force-added.
---
Usage:
  alpaca issue <approve|start|disable|enable|create|followup|list|search|show|broadcast|log|unlock>
Create, inspect, pause, re-enable, update, and unlock AlpacaLoop-managed issues.
Commands:
  approve    Post `/alpaca approve` to one AlpacaLoop-managed issue as its assignee; the next service scan records the approval.
  start      Post `/alpaca start` to one issue waiting for start approval as its assignee; the next service scan records the approval.
  disable    Add the disabled workflow rule to one or more open issues without changing their workflow status.
  enable     Remove the disabled workflow rule from one or more open issues without changing their workflow status.
  create     Create an AlpacaLoop-managed issue from worker-drafted prompt input or manual title/body input, with optional workflow overrides and reviewed drafts.
  followup   Create or dry-run an independent post-completion follow-up issue from an existing issue, carrying an optional request prompt and workflow selector for later follow-up execution.
  list       List tracker issues for triage with state, age, label, assignee, compact/detailed, markdown/text, or browser filters.
  search     Search tracker issues by title or portable provider-backed text query without loading comments, dependencies, or workflow details.
  show       Show one AlpacaLoop-managed issue with workflow status, parent/source chain, related children, PR details, and relevant comments.
  broadcast  Post or dry-run one shared tracker comment to explicit issue ids or filtered open AlpacaLoop queue issues.
  log        Inspect local issue run logs.
  unlock     Request release of AI: Running ownership for one or more issues so they can return to AI: Ready after the worker stops or ownership expires.
Notes:
  Use a subcommand help page for option details.
Use `alpaca issue <command> --help` for command-specific options.
---
Usage:
  alpaca issue approve --issue <id>
Post `/alpaca approve` to one AlpacaLoop-managed issue as its assignee; the next service scan records the approval.
Options:
  --issue <id>: Issue id. Required.
Notes:
  The command only posts `/alpaca approve`; the next service scan records the approval.
  The authenticated tracker user must match the issue's single assignee.
---
Usage:
  alpaca issue start --issue <id>
Post `/alpaca start` to one issue waiting for start approval as its assignee; the next service scan records the approval.
Options:
  --issue <id>: Issue id. Required.
Notes:
  The command only posts `/alpaca start`; the next service scan records the start approval.
  The authenticated tracker user must match the issue's single assignee.
  The issue must be waiting for start approval.
---
Usage:
  alpaca issue disable --issue <id[,id...]>
Add the disabled workflow rule to one or more open issues without changing their workflow status.
Options:
  --issue <id[,id...]>: One or more issue ids. Required.
Notes:
  This pauses AI processing for the issue by adding the AI: Disabled rule while preserving statuses such as AI: Ready, AI: Running, or AI: Needs Human.
---
Usage:
  alpaca issue enable --issue <id[,id...]>
Remove the disabled workflow rule from one or more open issues without changing their workflow status.
Options:
  --issue <id[,id...]>: One or more issue ids. Required.
Notes:
  This only removes the AI: Disabled rule. It does not approve, start, unlock, or move a waiting issue to AI: Ready.
---
Usage:
  alpaca issue create (--prompt <text> | --title <text> (--body <text> | --body-file <path|->)) [--save-draft] [--assignee <name> ...] [--label <label> ...] [--milestone <ref>] [--project <ref>] [--disabled] [workflow options]
  alpaca issue create --apply-draft <path|->
Create an AlpacaLoop-managed issue from worker-drafted prompt input or manual title/body input, with optional workflow overrides and reviewed drafts.
Options:
  Issue creation options:
    --prompt <text>: Ask the worker to draft the issue from a natural-language request.
    --title <text>: Manual issue title. Use with exactly one of --body or --body-file.
    --body <text>: Manual issue body text.
    --body-file <path|->: Read the manual issue body from a file or stdin.
    --assignee <name>: Assign a tracker user. Can be repeated. If omitted, the current authenticated tracker user is assigned.
    --label <label>: Add a tracker label. Can be repeated.
    --milestone <ref>: Attach a tracker milestone.
    --project <ref>: Attach a tracker project when supported by the provider.
    --disabled: Create with the disabled workflow rule.
    --save-draft: Save a machine-local reusable draft JSON and exit without applying changes.
    --apply-draft <path|->: Create the issue from a reviewed reusable draft JSON. Do not combine with prompt/manual inputs, --save-draft, metadata options, or workflow options.
  Initial workflow options:
    These use the same option keys as `/alpaca ...` issue comments, applied when the new issue is created. Issue create accepts option tokens only; tracker comment body text after `/alpaca ...` is separate same-issue replan context.
    --workflow <auto|auto_select|no_template|path>: Set the active workflow selector. auto may request a missing template; auto_select chooses an existing candidate, or falls back to no_template without workflow_select when no candidates exist; no_template uses the built-in default workflow.
    --pr-workflow <auto|auto_select|no_template|path>: Store the pull_request workflow selector. auto may request a missing template when that target runs; auto_select chooses an existing candidate, or falls back to no_template without workflow_select when no candidates exist; no_template uses the built-in default workflow for that target.
    --unplanned-workflow <auto|auto_select|no_template|path>: Store the unplanned workflow selector. auto may request a missing template when that target runs; auto_select chooses an existing candidate, or falls back to no_template without workflow_select when no candidates exist; no_template uses the built-in default workflow for that target.
      Automatic follow-up publication requires fresh workflow_closing provenance. During PR merge finalization, AlpacaLoop verifies the PR head or merge commit from a synchronized source/base workspace; if freshness cannot be proven, it stops automatic follow-up creation and asks for human review.
    --run-at <time> / --run-after <duration>: Schedule one future run.
    --every <duration> / --cron <expr>: Create a recurring parent issue.
    --first-run-at <time> / --first-run-after <duration> / --first-run-now: Control the first run of a recurring issue.
    --stop-at <time> / --stop-after <duration> / --stop-after-runs <count> / --stop-off: Control recurring auto-stop behavior.
    --schedule-off: Clear one-shot and recurring scheduling.
    --base-branch <value|default>: Override the stored base branch for this issue's workflow state and PR merge target.
    --issue-completion-target <pause-on-issue|pull-request|default>: Choose whether completed issue work pauses on the issue or moves to a pull request.
    --pr-review <never|if-needed|always|default>: Choose whether pull request review runs.
    --pr-merge <manual|auto|default>: Choose whether pull requests are merged manually or automatically.
    --default-reviewers <value[,value...]|default>: Override default PR reviewers. Comma-separated and repeatable.
    --default-worker <worker-id|default>: Override ordinary execution workers for this issue.
    --thinking-worker <worker-id|default>: Select the first worker for planning and draft-style runs; unavailable selections fall back to workers.default.
    --max-ai-runs <count|default>: Override the AI run count limit.
    --max-ai-hours <hours|off|default>: Override the AI work-hour limit.
    --recurring-max-active-children <count|default>: Override the maximum open recurring child issues for this parent.
    --recurring-update-child-title-after-plan <true|false|default>: Override whether recurring child issue titles are updated after planning.
    --followup-proposal <off|if_needed|always|default>: Choose follow-up proposal generation: off, if_needed, or always.
    --followup-proposal-approval <auto|confirm|confirm_if_needed|default>: Choose follow-up proposal approval: auto, confirm, or confirm_if_needed.
    --followup-preferred-workflow-template <path|no_template[,path...]|default>: Add priority follow-up template hints for recommendation only; not an allowlist and does not force creation. Comma-separated and repeatable.
    --followup-auto-maintain-templates <true|false|default>: Allow follow-up workflow selection to request or refresh missing templates when needed.
    --followup-max-main-work-issues <0..5|default>: Override the automatic mainWork follow-up issue cap for this source item.
    --followup-max-maintenance-issues <0..5|default>: Override the automatic maintenance follow-up issue cap for this source item.
    --foreign-approval-scope <external_only|all_foreign|default>: Override which foreign issues require approval.
    --workflow-start-new-plan <auto|confirm|conservative|aggressive|default>: Override start approval for newly planned work.
    --workflow-start-replan <auto|confirm|conservative|aggressive|default>: Override start approval for post-start replans.
    --workflow-start-scope <issue_only|issue_and_pr|default>: Override whether start approval applies to issue work only or issue and PR work.
    --requirements-setup-skills <auto|confirm|default>: Choose whether missing required skills create setup issues automatically or ask for confirmation.
    --requirements-setup-mcp <auto|confirm|default>: Choose whether missing required MCP servers create setup issues automatically or ask for confirmation.
Notes:
  Prompt mode discovers provider issue templates before drafting.
  Prompt mode drafts issue content, then runs workflow setup for explicit selector, schedule, worker, follow-up, and autofill options. Explicit template/no_template workflow selections skip workflow_select; no_template uses the built-in default workflow for the target. Auto and auto_select workflow selections are saved unresolved and handled during normal workflow setup after the issue exists.
  --save-draft stores explicit workflowOptions and setup/autofill workflowOptions; --apply-draft uses the saved JSON without rerunning workers.
  Prompt and manual modes create the issue immediately unless --save-draft is set.
  --save-draft writes the review JSON under machine-local ~/.alpaca/drafts/ and does not create the issue. Draft labels exclude managed workflow labels.
  GitHub and Gitea support --project. GitLab project binding is not supported yet.
Examples:
  alpaca issue create --prompt "Fix flaky login tests"
  alpaca issue create --prompt "Fix flaky login tests" --save-draft
  alpaca issue create --title "Investigate queue delay" --body "Find the cause and propose a fix."
  alpaca issue create --prompt "This repository is a TypeScript CLI for task automation. Create reusable workflows for bug fixes, PR reviews, unplanned maintenance, and follow-up work." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off
  alpaca issue create --prompt "Refresh workflow templates for this repository based on recent issue history and current docs." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off --every 30d --first-run-now
  alpaca issue create --prompt "Maintain workflow templates for weekly platform work." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off --cron "0 9 * * 1" --first-run-after 1h --stop-after-runs 5
  alpaca issue create --prompt "Create initial workflow templates for a small web app with frontend, backend, PR review, and follow-up maintenance flows." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off --default-worker claude --max-ai-runs 10
  alpaca issue create --apply-draft ~/.alpaca/drafts/.../issue-create-....json
---
Usage:
  alpaca issue followup --issue <id> [--prompt <text>] [--workflow <auto|auto_select|no_template|path>] [--dry-run]
Create or dry-run an independent post-completion follow-up issue from an existing issue, carrying an optional request prompt and workflow selector for later follow-up execution.
Options:
  --issue <id>: Source issue id. Required.
  --prompt <text>: Store the follow-up request in the created issue body. Timing or cadence written here can be picked up by normal workflow setup/autofill.
  --workflow <auto|auto_select|no_template|path>: Store the follow-up workflow selector. auto may request a missing template when the follow-up issue runs; auto_select chooses an existing candidate, or falls back to no_template without workflow_select when no candidates exist; no_template uses the built-in default follow-up workflow.
  --dry-run: Preview without creating the follow-up issue.
---
Usage:
  alpaca issue list [--web] [--state open|closed|all] [--days <number>] [--limit <number>] [--label <label> ...] [--me] [--assignee <login> ...] [--view compact|detailed] [--format text|markdown]
List tracker issues for triage with state, age, label, assignee, compact/detailed, markdown/text, or browser filters.
Options:
  --web: Open the matching tracker issue list in a browser instead of printing the CLI report.
  --state open|closed|all: Filter by tracker state.
  --days <number>: Limit the recency window.
  --limit <number>: Limit the printed report to the N most recently updated matching issues. Not valid with --web.
  --label <label>: Filter by label. Can be repeated.
  --me: Filter to issues assigned to the authenticated tracker user. Not valid with --web.
  --assignee <login>: Filter to issues assigned to a tracker user. Can be repeated. Not valid with --web.
  --view compact|detailed: Choose the amount of issue detail for text output. Markdown output uses report tables. Default: detailed.
  --format text|markdown: Choose output format. Default: markdown.
Notes:
  Text detailed output displays active /alpaca overrides and workflow selections when present.
  Markdown output summarizes human attention and current issue status in tables.
  Repeated assignee filters match issues assigned to any listed user.
  --limit applies after state, recency, label, and assignee filters, before loading issue details.
  --view and --format are not valid with --web.
  --me and --assignee are not valid with --web.
  Gitea issue list pages do not support --days with --web.
---
Usage:
  alpaca issue search (--title <text> | --query <text>) [--state open|closed|all] [--limit <number>] [--include-prs] [--format text|markdown]
Search tracker issues by title or portable provider-backed text query without loading comments, dependencies, or workflow details.
Options:
  --title <text>: Search issue titles. GitHub uses title search; GitLab and Gitea use provider search then title-filter results.
  --query <text>: Search broader provider text. GitHub searches title, body, and comments; GitLab searches title and description for issues and merge requests; Gitea uses its repository issue search string.
  --state open|closed|all: Filter by tracker state. Default: open.
  --limit <number>: Limit the report to the N most recently updated matching items. Default: 10.
  --include-prs: Include pull requests or merge requests in addition to issues.
  --format text|markdown: Choose output format. Default: text.
Notes:
  Use this as a fallback when compact issue list and bounded issue show output do not identify the relevant issue.
  --query is portable AlpacaLoop search text, not raw provider query syntax.
  Provider search scopes differ; comments are only guaranteed in GitHub query mode.
Examples:
  alpaca issue search --title "memory" --state all --limit 10 --format text
  alpaca issue search --query "history cache" --include-prs --limit 5 --format markdown
---
Usage:
  alpaca issue show --issue <id> [--view default|followup|full] [--parents 0|number|all] [--children 0|number|all] [--limit number|all] [--comments none|post-completion|all] [--pr none|summary|changes|commits|all] [--format text|markdown]
Show one AlpacaLoop-managed issue with workflow status, parent/source chain, related children, PR details, and relevant comments.
Options:
  --issue <id>: Issue id. Required.
  --view default|followup|full: Choose preset defaults. Default: default.
  --parents 0|number|all: Include parent/source chain depth.
  --children 0|number|all: Include child/downstream relation depth.
  --limit number|all: Cap unordered related issue/file/commit output. Default: 20.
  --comments none|post-completion|all: Choose comment timeline. followup view defaults to post-completion.
  --pr none|summary|changes|commits|all: Choose PR detail level.
  --format text|markdown: Choose output format. Default: markdown.
Notes:
  Presets: default = parents 1, children 1, limit 20, comments all, pr summary.
  followup = parents all, children 1, limit 20, comments post-completion, pr changes.
  full = parents all, children all, limit 20, comments all, pr all. Add --limit all for exhaustive output.
---
Usage:
  alpaca issue broadcast (--message <text> | --message-file <path|->) (--issue <id[,id...]> | --open [--status <bucket> ...] [--label <label> ...]) [--dry-run]
Post or dry-run one shared tracker comment to explicit issue ids or filtered open AlpacaLoop queue issues.
Options:
  --message <text>: Comment text.
  --message-file <path|->: Read comment text from a file or stdin.
  --issue <id[,id...]>: Target explicit issue ids.
  --open: Target open AlpacaLoop queue issues.
  --status <bucket>: With --open, restrict target statuses. Can be repeated.
  --label <label>: With --open, restrict target labels. Can be repeated.
  --dry-run: Preview selected targets without posting.
Notes:
  Specify exactly one message source: --message or --message-file.
  Specify exactly one selector: --issue or --open.
  --open defaults to ai-ready, ai-running, and ai-needs-human.
  --status and --label are only valid with --open.
---
Usage:
  alpaca issue log <list|show|search>
Inspect local issue run logs.
Commands:
  list    List machine-local issue run log files captured from worker executions for later inspection or debugging.
  show    Show machine-local worker logs for one issue, with optional tailing to inspect recent execution output.
  search  Search machine-local issue run logs for text and optionally include surrounding context lines.
Notes:
  Use a subcommand help page for option details.
Use `alpaca issue log <command> --help` for command-specific options.
---
Usage:
  alpaca issue log list
List machine-local issue run log files captured from worker executions for later inspection or debugging.
---
Usage:
  alpaca issue log show --issue <id> [--tail <lines>]
Show machine-local worker logs for one issue, with optional tailing to inspect recent execution output.
Options:
  --issue <id>: Issue id. Required.
  --tail <lines>: Show only the last N lines.
---
Usage:
  alpaca issue log search --query <text> [--context <lines>]
Search machine-local issue run logs for text and optionally include surrounding context lines.
Options:
  --query <text>: Search text. Required.
  --context <lines>: Include N context lines around matches. Default: 0.
---
Usage:
  alpaca issue unlock --issue <id[,id...]>
Request release of AI: Running ownership for one or more issues so they can return to AI: Ready after the worker stops or ownership expires.
Options:
  --issue <id[,id...]>: One or more issue ids. Required.
Notes:
  The next worker starts after the current worker stops or ownership expires.
---
Usage:
  alpaca state <patch|restore>
Maintain canonical workflow state comments.
Commands:
  patch    Preview or apply canonical workflow state comment schema migrations across selected issues, writing backups before non-dry-run updates.
  restore  Restore canonical workflow state comments from a JSONL backup, with dry-run and hash-safety controls for targeted recovery.
Use `alpaca state <command> --help` for command-specific options.
---
Usage:
  alpaca state patch [--issue <id[,id...]>] [--state open|closed|all] [--dry-run]
Preview or apply canonical workflow state comment schema migrations across selected issues, writing backups before non-dry-run updates.
Options:
  --issue <id[,id...]>: Check or patch one or more tracker issue ids.
  --state open|closed|all: Filter target issues by tracker state. Default: open.
  --dry-run: Preview whether canonical workflow state comments can migrate without updating tracker comments.
Notes:
  Use --dry-run --state open before publishing workflow state schema or patch changes that could affect existing open issues.
  --issue is for targeted checks; --state is for list-wide checks.
  Non-dry-run patch asks for confirmation in an interactive terminal before updating tracker comments.
  Only the latest canonical workflow state comment on each issue is patched; successful non-dry-run updates write a JSONL backup before changing tracker comments.
---
Usage:
  alpaca state restore --backup-file <path> [--issue <id[,id...]>] [--dry-run] [--force]
Restore canonical workflow state comments from a JSONL backup, with dry-run and hash-safety controls for targeted recovery.
Options:
  --backup-file <path>: JSONL backup file created by state patch or state restore. Required.
  --issue <id[,id...]>: Restrict restore to one or more tracker issue ids.
  --dry-run: Preview restore results without updating comments.
  --force: Restore even when the current comment body hash differs from the backup.
Notes:
  Non-dry-run restore asks for confirmation in an interactive terminal before updating tracker comments.
  --force only ignores body hash mismatches; restore still skips when a newer canonical workflow state comment exists. Successful non-dry-run restores write a .restore.jsonl backup before changing tracker comments.
---
Usage:
  alpaca labels <sync>
Manage configured tracker labels.
Commands:
  sync  Create or reconcile the configured AlpacaLoop-managed labels in the tracker for the current repository.
Docs:
  alpaca docs show config
Use `alpaca labels <command> --help` for command-specific options.
---
Usage:
  alpaca labels sync
Create or reconcile the configured AlpacaLoop-managed labels in the tracker for the current repository.
Docs:
  alpaca docs show config
---
Usage:
  alpaca catalog <topics>
Inspect shared catalog metadata used by skill and MCP search.
Commands:
  topics  Inspect shared catalog topics.
Notes:
  Use a subcommand help page for option details.
Use `alpaca catalog <command> --help` for command-specific options.
---
Usage:
  alpaca catalog topics <list>
Inspect shared catalog topics.
Commands:
  list  Print shared skill and MCP catalog topic metadata as JSON, combining active system topics with repo-local user topics.
Notes:
  Use a subcommand help page for option details.
Use `alpaca catalog topics <command> --help` for command-specific options.
---
Usage:
  alpaca catalog topics list
Print shared skill and MCP catalog topic metadata as JSON, combining active system topics with repo-local user topics.
Notes:
  Topics are the shared vocabulary stored in catalog metadata.json and used by skill and MCP catalog entries.
  The command always includes active system topics and repo-local user topics.
---
Usage:
  alpaca capability <list|search>
Inspect skills and MCP servers through one read-only discovery view.
Commands:
  list    List installed skill and MCP capabilities as JSON, hiding refs excluded from workflow requires by default.
  search  Search installed, catalog-backed, discovery-only, and provider candidates across skill and MCP sources as JSON.
Notes:
  Use capability for cross-type discovery before deciding whether a workflow requires a skill or MCP server.
  Use skill or mcp commands for install, create, catalog, or verify operations.
Use `alpaca capability <command> --help` for command-specific options.
---
Usage:
  alpaca capability list [--for <worker-id>|all] [--include-excluded]
List installed skill and MCP capabilities as JSON, hiding refs excluded from workflow requires by default.
Options:
  --for <worker-id>|all: Limit the result to one worker runtime or all configured workers.
  --include-excluded: Include candidates that are visible but excluded from workflow requires, with exclusion reason metadata.
Notes:
  Capability list is read-only and does not install, create, or verify anything.
  Use skill list or mcp verify/list for final requires.skills / requires.mcp refs.
---
Usage:
  alpaca capability search <query> [--for <worker-id>|all] [--installed-only|--installable-only] [--include-excluded]
Search installed, catalog-backed, discovery-only, and provider candidates across skill and MCP sources as JSON.
Options:
  --for <worker-id>|all: Search capabilities for one worker runtime or all configured workers.
  --installed-only: Return only capabilities already visible in installed inventory.
  --installable-only: Return only install candidates.
  --include-excluded: Include candidates that are visible but excluded from workflow requires, with exclusion reason metadata.
Notes:
  Search results are discovery candidates; they are not automatically valid workflow requirements.
  Use skill install/create/list and mcp install/create/verify/list for the actual resolution path.
---
Usage:
  alpaca skill <list|search|install|create|catalog>
Inspect worker skills and repo-visible installable skill catalog entries.
Commands:
  list     List installed worker skills as JSON, including whether each ref is usable in workflow requires.skills for a configured worker.
  search   Search installed skills, repo/system catalog entries, and provider marketplaces as JSON, optionally asking a worker to rank matches.
  install  Install a selected file, GitHub, Claude plugin, or Codex plugin skill candidate for one worker runtime, then print install results as JSON.
  create   Create a skill-resolution tracker issue, or save/apply reviewed draft JSON, without writing SKILL.md directly.
  catalog  Manage repo-visible installable skill catalog entries.
Notes:
  Use a subcommand help page for option details.
Use `alpaca skill <command> --help` for command-specific options.
---
Usage:
  alpaca skill list [--for <worker-id>] [--include-excluded]
List installed worker skills as JSON, including whether each ref is usable in workflow requires.skills for a configured worker.
Options:
  --for <worker-id>: Limit the result to one worker runtime.
  --include-excluded: Include skills excluded from workflow requires, with exclusion reason metadata.
Notes:
  Use the JSON ref field in workflow requires.skills only when usableForRequiredSkills is true.
  This command is read-only and does not install or create skills.
---
Usage:
  alpaca skill search <query> [--for <worker-id>|all] [--installed-only|--installable-only] [--with-worker] [--include-excluded]
Search installed skills, repo/system catalog entries, and provider marketplaces as JSON, optionally asking a worker to rank matches.
Options:
  --for <worker-id>|all: Search skills for one worker runtime or all configured workers.
  --installed-only: Return only skills already visible in alpaca skill list.
  --installable-only: Return only catalog or marketplace install candidates.
  --with-worker: Ask a configured worker to inspect read-only catalog/search commands and prioritize semantic matches.
  --include-excluded: Include skills excluded from workflow requires, with exclusion reason metadata.
Notes:
  Search results are install and discovery candidates; use alpaca skill list to inspect refs usable in workflow requires.skills.
  Installable results come from the effective skill catalog and Claude/Codex provider plugin marketplace search.
  Provider plugin results are install mechanisms for enabling skills, not plugin requirements to store in workflows.
  This command is read-only and does not install or create skills.
  --with-worker never calls search recursively with --with-worker; if the worker cannot run, normal search results are returned with worker fallback metadata.
---
Usage:
  alpaca skill install --source <source-uri> --for <worker-id> [--overwrite] [--plugin-scope project|user|local]
  alpaca skill install --search <query> --for <worker-id> [--overwrite] [--plugin-scope project|user|local] [--include-excluded]
Install a selected file, GitHub, Claude plugin, or Codex plugin skill candidate for one worker runtime, then print install results as JSON.
Options:
  --source <source-uri>: Use a file://, github+https://, claude-plugin://, or codex-plugin:// source URI.
  --search <query>: Search first; if multiple installable candidates remain, an interactive terminal prompts you to choose one.
  --for <worker-id>: Install for one worker runtime.
  --overwrite: Replace an existing repo-local skill directory.
  --plugin-scope project|user|local: Claude plugin install scope. Defaults to project.
  --include-excluded: Allow --search to select candidates excluded from workflow requires. Installed results can still be unusable as requires.skills.
Notes:
  File and GitHub sources write repo-local worker skill directories.
  Install does not automatically install npm packages, CLI tools, companion skills, OAuth credentials, browser login, or other runtime setup.
  Claude plugin sources require --for claude, are installed through claude plugin install, and are not repo-local skill directories.
  Codex plugin sources require --for codex, are installed through codex app-server plugin/install, and are not repo-local skill directories.
  AlpacaLoop has no alpaca plugin command, plugin catalog, plugin DB, or requires.plugin workflow field.
  When --search cannot select exactly one candidate outside an interactive terminal, the command prints alpaca.skillInstallSelectionRequired without installing.
  When --search selects a catalog-backed file or GitHub source, the catalog id becomes the repo-local install directory and requires.skills ref.
  Direct --source installs are allowed even when the source matches a requires exclusion; the JSON result includes excludedFromRequires and excludeReason when the installed skill must not be used in requires.skills.
  After install, inspect the skill docs for dependencies and auth requirements, complete safe non-interactive setup, then run alpaca skill list --for <worker> and a documented help, version, or smoke command when possible.
---
Usage:
  alpaca skill create --prompt <text> [--for <worker-id>|all] [--save-draft]
  alpaca skill create --apply-draft <path|->
Create a skill-resolution tracker issue, or save/apply reviewed draft JSON, without writing SKILL.md directly.
Options:
  --prompt <text>: Ask a worker to draft a short title and capability summary for the skill-resolution issue.
  --for <worker-id>|all: Target one worker runtime or all configured workers. Defaults to all.
  --save-draft: Save a machine-local reusable draft JSON and exit without applying changes.
  --apply-draft <path|->: Create the issue from a reviewed draft.
Notes:
  This command creates an issue for skill resolution; it does not write SKILL.md directly.
  By default it drafts with a worker first, then creates the issue immediately. Use --save-draft to save the final review JSON under machine-local ~/.alpaca/drafts/ instead.
  The issue is bound to __system/skill-resolution.md using the ejected workflow when present, otherwise the packaged system workflow.
---
Usage:
  alpaca skill catalog <list|add|import-github|remove>
Manage repo-visible installable skill catalog entries.
Commands:
  list           List repo-visible installable skill catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.
  add            Add or replace one repo-local user skill catalog entry with worker-specific or default install sources.
  import-github  Import every SKILL.md under a GitHub repository directory as repo-local installable skill catalog entries for selected worker runtimes.
  remove         Remove one repo-local user skill catalog entry by id; packaged or ejected system entries are not removed.
Notes:
  User entries live in .alpaca/catalog/skill.json; packaged system entries live in package-assets/system/catalog/skill.json.
  Ejected system entries live in .alpaca/catalog/__system/skill.json and replace packaged system entries for that repository.
  Packaged and ejected system catalogs are AlpacaLoop-curated install candidates. Provider marketplaces are searched separately by skill search.
  Catalog entries are install candidates; usable workflow requires.skills refs still come from alpaca skill list.
  Use a subcommand help page for option details.
Use `alpaca skill catalog <command> --help` for command-specific options.
---
Usage:
  alpaca skill catalog list [--include-system]
List repo-visible installable skill catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.
Options:
  --include-system: Include packaged system catalog entries in the JSON items when the system catalog has not been ejected.
Notes:
  Ejected system catalog entries are repo-visible and shown by default; packaged system entries stay hidden by default to keep this command focused on repo-local catalog entries.
  Claude/Codex provider marketplace search is resolved by skill search and is not synchronized into system or user catalog files.
  Sources are install candidates for alpaca skill install --source, not requires.skills refs.
---
Usage:
  alpaca skill catalog add --id <id> --description <text> [--source <source-uri>] [--codex-source <source-uri>] [--claude-source <source-uri>]
Add or replace one repo-local user skill catalog entry with worker-specific or default install sources.
Options:
  --id <id>: Stable catalog entry id.
  --description <text>: Short capability description.
  --source <source-uri>: Default install source for compatible workers.
  --codex-source <source-uri>: Codex-specific install source.
  --claude-source <source-uri>: Claude-specific install source.
Notes:
  At least one source option is required.
  Adding an existing user entry replaces the user entry.
  System entry ids cannot be added as user entries; run alpaca eject catalog to edit them.
---
Usage:
  alpaca skill catalog import-github --repo <owner/repo> --path <dir> [--ref <git-ref>] [--for <worker-id>|all] [--overwrite]
Import every SKILL.md under a GitHub repository directory as repo-local installable skill catalog entries for selected worker runtimes.
Options:
  --repo <owner/repo>: GitHub repository containing skills.
  --path <dir>: Directory to scan for SKILL.md files.
  --ref <git-ref>: Git ref to read. Defaults to main.
  --for <worker-id>|all: Store imported sources for one worker or as default sources. Defaults to all.
  --overwrite: Replace existing user entries with imported entries.
Notes:
  Imported ids come from SKILL.md frontmatter name when valid, otherwise the skill directory name.
  System entry ids cannot be imported as user entries; run alpaca eject catalog to edit them.
---
Usage:
  alpaca skill catalog remove --id <id>
Remove one repo-local user skill catalog entry by id; packaged or ejected system entries are not removed.
Options:
  --id <id>: User catalog entry id to remove.
Notes:
  System entries are not removed by this command.
---
Usage:
  alpaca mcp <list|search|install|create|verify|catalog>
Inspect, install, resolve, verify, and catalog worker MCP servers.
Commands:
  list     List MCP servers visible to worker runtimes as JSON, including diagnostics about usable server and tool refs.
  search   Search installed MCP servers and catalog entries as JSON, optionally asking a worker to rank matches.
  install  Install one safe catalog-backed MCP server into a worker runtime.
  create   Create an MCP-resolution tracker issue, or save/apply reviewed draft JSON, without editing MCP catalog or worker config directly.
  verify   Verify configured MCP server or tool refs against configured workers before declaring workflow requires.mcp.
  catalog  Manage repo-visible MCP catalog entries.
Notes:
  Use a subcommand help page for option details.
Use `alpaca mcp <command> --help` for command-specific options.
---
Usage:
  alpaca mcp list [--for <worker-id>|all] [--include-excluded]
List MCP servers visible to worker runtimes as JSON, including diagnostics about usable server and tool refs.
Options:
  --for <worker-id>|all: Limit the result to one worker runtime or all configured workers.
  --include-excluded: Include MCP refs excluded from workflow requires, with exclusion reason metadata.
Notes:
  Codex entries are inspected through codex app-server MCP status and must expose tools before they can satisfy required MCP refs.
  Claude worker entries are inspected with claude mcp list when CLAUDE_CONFIG_DIR is available; .mcp.json project entries are shown as shared config but are not treated as worker-usable by themselves.
  Custom worker entries read .mcp.json and .pi/mcp.json through the Pi MCP adapter; cached tool metadata is shown when available.
---
Usage:
  alpaca mcp search <query> [--for <worker-id>|all] [--installed-only|--installable-only] [--with-worker] [--include-excluded]
Search installed MCP servers and catalog entries as JSON, optionally asking a worker to rank matches.
Options:
  --for <worker-id>|all: Search MCP servers for one worker runtime or all configured workers.
  --installed-only: Return only MCP servers already returned by alpaca mcp list.
  --installable-only: Return only safe catalog entries with an install server spec.
  --with-worker: Ask a configured worker to inspect read-only catalog/search commands and prioritize semantic matches.
  --include-excluded: Include MCP candidates excluded from workflow requires, with exclusion reason metadata.
Notes:
  Installed inspection diagnostics are included in diagnostics; catalog candidates can still be returned when runtime inspection fails.
  Catalog entries without servers are discovery-only search leads and are hidden by --installable-only.
  --with-worker never calls search recursively with --with-worker; if the worker cannot run, normal search results are returned with worker fallback metadata.
---
Usage:
  alpaca mcp install --id <catalog-id> --for <worker-id> [--name <server-name>] [--profile <auth-profile-id>] [--overwrite]
  alpaca mcp install --search <query> --for <worker-id> [--name <server-name>] [--profile <auth-profile-id>] [--overwrite] [--include-excluded]
Install one safe catalog-backed MCP server into a worker runtime.
Options:
  --id <catalog-id>: Install a specific MCP catalog entry.
  --search <query>: Search installable catalog entries first; installs only when one candidate is selected.
  --for <worker-id>: Install for one worker runtime.
  --name <server-name>: Override the configured MCP server name.
  --profile <auth-profile-id>: Use one saved worker auth profile environment.
  --overwrite: Remove an existing MCP server with the same name before adding it.
  --include-excluded: Allow --search to select candidates excluded from workflow requires. Installed refs still need mcp verify before use in requires.mcp.
Notes:
  Codex installs use codex mcp add with the selected worker CODEX_HOME. Claude installs use claude mcp add-json --scope user with the selected worker CLAUDE_CONFIG_DIR. Custom worker installs merge into project .mcp.json.
  Catalog entries must declare setup.safeAutoInstall: true and include a server spec for the selected worker target. Discovery-only catalog entries must be completed before install.
  Install does not complete OAuth, token, admin approval, or browser login steps. Follow nextSteps in the JSON result.
  Direct --id installs are allowed even when the catalog entry matches a requires exclusion; the JSON result includes excludedFromRequires and excludeReason when the installed ref must not be used in requires.mcp.
  The returned ref is a candidate value; declare requires.mcp only after alpaca mcp verify reports the server or tool as usable by the worker.
---
Usage:
  alpaca mcp create --prompt <text> [--for <worker-id>|all] [--save-draft]
  alpaca mcp create --apply-draft <path|->
Create an MCP-resolution tracker issue, or save/apply reviewed draft JSON, without editing MCP catalog or worker config directly.
Options:
  --prompt <text>: Ask a worker to draft a short title and capability summary for the MCP-resolution issue.
  --for <worker-id>|all: Target one worker runtime or all configured workers. Defaults to all.
  --save-draft: Save a machine-local reusable draft JSON and exit without applying changes.
  --apply-draft <path|->: Create the issue from a reviewed draft.
Notes:
  This command creates an issue for MCP resolution; it does not write MCP catalog entries or worker MCP config directly.
  By default it drafts with a worker first, then creates the issue immediately. Use --save-draft to save the final review JSON under machine-local ~/.alpaca/drafts/ instead.
  The issue is bound to __system/mcp-resolution.md using the ejected workflow when present, otherwise the packaged system workflow.
---
Usage:
  alpaca mcp verify [--for <worker-id>|all] [--ref <mcp-ref> ...]
Verify configured MCP server or tool refs against configured workers before declaring workflow requires.mcp.
Options:
  --for <worker-id>|all: Verify against one worker runtime or all configured workers.
  --ref <mcp-ref>: Verify a specific ref such as github, github/list_issues, codex:github, claude:github/list_issues, or lmstudio-coder:github. Can be repeated.
Notes:
  Codex verification requires codex app-server MCP status to expose at least one tool for the target server.
  Claude verification uses worker CLAUDE_CONFIG_DIR when available and treats connected servers as usable for server refs; tool refs still require tool names.
  Custom worker verification uses .mcp.json and .pi/mcp.json server config plus Pi MCP adapter cache when tool names are known.
---
Usage:
  alpaca mcp catalog <list|add|remove>
Manage repo-visible MCP catalog entries.
Commands:
  list    List repo-visible MCP install catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.
  add     Add or replace one repo-local MCP catalog entry from a JSON object read from a file or stdin.
  remove  Remove one repo-local MCP catalog entry by id; packaged or ejected system entries are not removed.
Notes:
  Catalog entries may be install candidates or discovery-only setup leads; workflow requires.mcp refs still come from alpaca mcp verify/list.
  Installable catalog entries require a server spec plus setup.safeAutoInstall: true.
  Use a subcommand help page for option details.
Use `alpaca mcp catalog <command> --help` for command-specific options.
---
Usage:
  alpaca mcp catalog list [--include-system]
List repo-visible MCP install catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.
Options:
  --include-system: Include packaged system catalog entries in the JSON items when the system catalog has not been ejected.
Notes:
  Ejected system catalog entries are repo-visible and shown by default.
  Packaged system entries may include discovery-only MCP leads without servers; those are searchable but not installable until a reviewed server spec is added.
---
Usage:
  alpaca mcp catalog add --entry <path|-> [--overwrite]
Add or replace one repo-local MCP catalog entry from a JSON object read from a file or stdin.
Options:
  --entry <path|->: Read a single MCP catalog entry JSON object from a file or stdin.
  --overwrite: Replace an existing user entry with the same id.
---
Usage:
  alpaca mcp catalog remove --id <id>
Remove one repo-local MCP catalog entry by id; packaged or ejected system entries are not removed.
Options:
  --id <id>: User catalog entry id to remove.
Notes:
  System entries are not removed by this command.
---
Usage:
  alpaca workflow <create|update|delete|lint|list>
Create, update, delete, validate, and list reusable workflow templates.
Commands:
  create  Draft reusable workflow template decisions from prompt/template-set input, or create one from manual body/scaffold, with optional required skills/MCP and reviewed drafts.
  update  Update a fixed workflow template from a prompt, or use template-set mode for related create/update/reuse changes with reviewed draft application.
  delete  Delete one repo-local workflow template, blocking when references remain unless a reviewed cleanup draft is saved and applied.
  lint    Validate one or all workflow templates locally, including structure, nested references, section order, and required capability availability.
  list    List workflow templates or references to one template, optionally including system templates and printing text or JSON output.
Notes:
  Use a subcommand help page for option details.
Use `alpaca workflow <command> --help` for command-specific options.
---
Usage:
  alpaca workflow create --prompt <text> [--path <path>] [--description <text>] [--target <target> ...] [--no-auto-select] [--required-skill <ref> ...] [--required-mcp <ref> ...] [--save-draft]
  alpaca workflow create --prompt <text> --template-set [--save-draft]
  alpaca workflow create --path <path> [--description <text>] [--target <target> ...] [--no-auto-select] [--required-skill <ref> ...] [--required-mcp <ref> ...] [--body <text> | --body-file <path|->] [--save-draft]
  alpaca workflow create --apply-draft <path|->
Draft reusable workflow template decisions from prompt/template-set input, or create one from manual body/scaffold, with optional required skills/MCP and reviewed drafts.
Options:
  --prompt <text>: Ask the worker to inspect the catalog and choose create/update/reuse template action.
  --template-set: With --prompt, draft the smallest cohesive set of create/update/reuse template changes.
  --path <path>: Template path. Required in manual mode; optional override in prompt mode.
  --description <text>: Template description override.
  --target issue|pull_request|unplanned|followup: Declare where this template can be selected. `recurring` is schedule state, not a target. Can be repeated. Default: issue.
  --no-auto-select: Keep the template listed and valid, but exclude it from automatic selection.
  --required-skill <ref>: Declare a requires.skills ref from alpaca skill list. Can be repeated.
  --required-mcp <ref>: Declare a requires.mcp ref from alpaca mcp verify/list. Can be repeated.
  --body <text>: Manual template body.
  --body-file <path|->: Read manual template body from a file or stdin.
  --save-draft: Save a machine-local reusable draft JSON and exit without applying changes.
  --apply-draft <path|->: Apply a reviewed workflow create draft JSON. Do not combine with prompt/manual inputs, --save-draft, or template overrides.
Notes:
  Prompt mode inspects the existing catalog and may reuse an existing template, update a close template, or create a new template only for a missing reusable workflow type.
  Prompt mode drafts path, description, targets, automatic selection eligibility, required skills/MCP refs, and body unless overridden.
  Prefer <domain>/<role>-<scope>.md paths; reuse an existing domain folder for the same purpose before creating a new folder, and avoid synonym folders for the same domain.
  Template-set mode cannot be combined with template overrides or manual body input, may move update_existing paths, and should not create one template per issue step, file, bullet, phase, or generic checklist item.
  Use @workflow only when the referenced template should become a nested workflow step; use a plain .alpaca/workflows/foo.md path for reference-only guidance.
  Recurring behavior uses issue workflow templates plus schedule state such as --every or --cron.
  Manual mode without --body or --body-file writes a generic scaffold.
  New templates explicitly write updateMode: flexible.
  Prompt and manual modes write templates immediately unless --save-draft is set.
  --save-draft writes the review JSON under machine-local ~/.alpaca/drafts/ and does not write templates.
  --apply-draft applies reviewed draft JSON without rerunning the worker.
---
Usage:
  alpaca workflow update [--path <template.md>] --prompt <text> [--template-set] [--save-draft]
  alpaca workflow update --apply-draft <path|->
Update a fixed workflow template from a prompt, or use template-set mode for related create/update/reuse changes with reviewed draft application.
Options:
  --path <template.md>: Existing template path. If omitted in an interactive terminal, AlpacaLoop prompts you to choose a template.
  --prompt <text>: Requested improvement. Required in prompt mode.
  --template-set: Allow the worker to split the target into the smallest cohesive create/update/reuse template changes.
  --save-draft: Save a machine-local reusable draft JSON and exit without applying changes.
  --apply-draft <path|->: Apply a reviewed workflow update draft JSON. Do not combine with --path, --prompt, --template-set, or --save-draft.
Notes:
  Updates the template file, not workflow target selections stored on tracker items.
  Plain prompt mode updates only the fixed target path; use --template-set when the request may split responsibilities or require related create/reuse decisions.
  Template-set mode uses the target path as an anchor and may create, update, reuse, or move related reusable templates without creating one template per issue step.
  Prefer <domain>/<role>-<scope>.md paths; reuse an existing domain folder for the same purpose before creating a new folder, and avoid synonym folders for the same domain.
  Use @workflow only when the referenced template should become a nested workflow step; use a plain .alpaca/workflows/foo.md path for reference-only guidance.
  New templates created by template-set updates explicitly write updateMode: flexible.
  Prompt mode writes templates immediately unless --save-draft is set.
  --save-draft writes the review JSON under machine-local ~/.alpaca/drafts/ and does not write templates.
  --apply-draft applies reviewed draft JSON without rerunning the worker and checks update base digests before writing.
---
Usage:
  alpaca workflow delete --path <template.md> [--dry-run]
  alpaca workflow delete --path <template.md> [--save-draft]
  alpaca workflow delete --path <template.md> --cleanup-references --save-draft
  alpaca workflow delete --apply-draft <path|->
Delete one repo-local workflow template, blocking when references remain unless a reviewed cleanup draft is saved and applied.
Options:
  --path <template.md>: Repo-local workflow template to delete. System templates cannot be deleted.
  --dry-run: Show the delete action or remaining references without deleting files.
  --cleanup-references: Ask the worker to update editable referring templates before deleting the target. Must be combined with --save-draft.
  --save-draft: Save a machine-local reusable draft JSON and exit without applying changes.
  --apply-draft <path|->: Apply a reviewed workflow delete draft JSON. Do not combine with --path, --cleanup-references, --dry-run, or --save-draft.
Notes:
  Delete checks workflow template references from @workflow, Markdown links, plain .alpaca/workflows/foo.md paths, and workflow template config selectors.
  Use `workflow list --references-to <template.md>` to inspect references before deleting.
  --dry-run is a preview mode and cannot be combined with --save-draft.
  Without --cleanup-references, --save-draft saves a reviewed single-template delete draft.
  --cleanup-references removes references to the target template; it does not cascade-delete other templates.
  Config selectors, system templates, strict templates, and disabled templates are not edited by cleanup drafts.
---
Usage:
  alpaca workflow lint [--path <path>]
Validate one or all workflow templates locally, including structure, nested references, section order, and required capability availability.
Options:
  --path <path>: Validate one template instead of all templates.
Notes:
  With --path, required skill/MCP availability is strict for the selected template tree.
  Without --path, required capability availability is reported as warnings so unselected templates do not fail full-catalog checks.
---
Usage:
  alpaca workflow list [--include-system] [--target issue|pull_request|unplanned|followup] [--format text|json]
  alpaca workflow list --references-to <template.md> [--format text|json]
List workflow templates or references to one template, optionally including system templates and printing text or JSON output.
Options:
  --include-system: Include system workflows under __system/ in template-list mode. Reference-list mode always includes system sources so it matches delete checks.
  --target issue|pull_request|unplanned|followup: Filter by workflow target.
  --references-to <template.md>: List workflow templates or config selectors that reference the target template. Cannot be combined with --target.
  --format text|json: Choose output format. Default: text.
---
Usage:
  alpaca event-hook <add|list|remove|test|create|update|config>
Manage publish event hooks.
Commands:
  config  Configure machine-local publish event hook settings, including the user-scoped hook file directory used by user hooks.
  add     Register an existing repo-scoped or user-scoped publish event hook file for selected triggers, one repo or all repos as allowed.
  create  Ask a worker to create a repo or user publish event hook file from a prompt, then register it or save/apply a reviewed draft.
  update  Ask a worker to update an already registered repo or user publish event hook file from a prompt, or save/apply a reviewed draft.
  list    List configured repo and/or user publish event hooks for one repository or all registered repositories.
  remove  Remove a repo-scoped or user-scoped publish event hook registration by path without deleting unrelated hook files.
  test    Run one publish event hook with sample completed-event JSON to test its runner and observe any real side effects.
Notes:
  Repo-scoped hooks are stored in alpaca.config.json. User-scoped hook registrations are stored machine-locally, and hook files must live under the configured user directory.
  Program hooks are supported on Linux, macOS, and WSL2. Native Windows execution is not a v1 target.
  Use a subcommand help page for option details.
Docs:
  alpaca docs show event-hooks
Use `alpaca event-hook <command> --help` for command-specific options.
---
Usage:
  alpaca event-hook config set --user-dir <path>
  alpaca event-hook config show
Configure machine-local publish event hook settings, including the user-scoped hook file directory used by user hooks.
Options:
  --user-dir <path>: Directory for user-scoped event hook files. Relative paths are resolved from the command cwd and saved as absolute paths.
Notes:
  Set this before using event-hook add/create/update --scope user. The hidden ~/.alpaca/event-hooks directory stores registrations and ledgers only.
Docs:
  alpaca docs show event-hooks
---
Usage:
  alpaca event-hook add --scope repo [--cwd <path>] --path <path> [--runner <command>] --on <trigger> [--on <trigger> ...]
  alpaca event-hook add --scope user [--cwd <path> | --all-repos] --path <path> [--runner <command>] --on <trigger> [--on <trigger> ...]
Register an existing repo-scoped or user-scoped publish event hook file for selected triggers, one repo or all repos as allowed.
Options:
  --scope repo|user: repo writes alpaca.config.json; user writes machine-local hook registration.
  --cwd <path>: Target one repository directory.
  --all-repos: With --scope user, register one global machine-local hook for every tracked repository.
  --path <path>: Hook file path. Repo-scoped hooks must be repository-relative. User-scoped paths must be relative to the configured user directory.
  --runner <command>: Runner command. Defaults from extension: .md worker, .js/.mjs/.cjs node, .py python3, .sh bash.
  --on <trigger>: Trigger token such as aiNeedsHuman, completed, issueCreated, workerFailed, systemFailed, or all. Can be repeated or comma-separated.
Notes:
  For project-local user hooks, run the command once per repository with --cwd <path> or from that repository.
  AlpacaLoop does not merge identical project-local hook registrations into a global hook automatically.
Docs:
  alpaca docs show event-hooks
---
Usage:
  alpaca event-hook create --scope repo [--cwd <path>] [--path <path>] [--runner <command>] --on <trigger> --prompt <text> [--save-draft]
  alpaca event-hook create --scope user [--cwd <path> | --all-repos] [--path <path>] [--runner <command>] --on <trigger> --prompt <text> [--save-draft]
  alpaca event-hook create --apply-draft <path|->
Ask a worker to create a repo or user publish event hook file from a prompt, then register it or save/apply a reviewed draft.
Options:
  --scope repo|user: repo writes alpaca.config.json; user writes machine-local hook registration.
  --cwd <path>: Target one repository directory.
  --all-repos: With --scope user, create one global machine-local hook for every tracked repository.
  --path <path>: Hook file path. If omitted, AlpacaLoop derives a path from the prompt. User-scoped paths are relative to the configured user directory.
  --runner <command>: Runner command. Defaults from extension; without --path, only worker, node, python3, and bash can be inferred.
  --on <trigger>: Trigger token. Can be repeated or comma-separated.
  --prompt <text>: Natural-language request for the hook body.
  --save-draft: Save a reusable draft JSON and do not write the hook file or registration.
  --apply-draft <path|->: Apply a saved event-hook draft without running a worker.
Docs:
  alpaca docs show event-hooks
---
Usage:
  alpaca event-hook update --scope repo [--cwd <path>] --path <path> --prompt <text> [--save-draft]
  alpaca event-hook update --scope user [--cwd <path> | --all-repos] --path <path> --prompt <text> [--save-draft]
  alpaca event-hook update --apply-draft <path|->
Ask a worker to update an already registered repo or user publish event hook file from a prompt, or save/apply a reviewed draft.
Options:
  --scope repo|user: Select the registry that already contains the hook.
  --cwd <path>: Target one repository directory.
  --all-repos: With --scope user, target the global machine-local hook registry.
  --path <path>: Registered hook file path to update. User-scoped paths are relative to the configured user directory.
  --prompt <text>: Natural-language request for the file update.
  --save-draft: Save a reusable draft JSON and do not write the hook file.
  --apply-draft <path|->: Apply a saved event-hook update draft without running a worker.
Docs:
  alpaca docs show event-hooks
---
Usage:
  alpaca event-hook list [--scope repo|user|all] [--cwd <path> | --all-repos]
List configured repo and/or user publish event hooks for one repository or all registered repositories.
Docs:
  alpaca docs show event-hooks
---
Usage:
  alpaca event-hook remove --scope repo [--cwd <path>] --path <path>
  alpaca event-hook remove --scope user [--cwd <path> | --all-repos] --path <path>
Remove a repo-scoped or user-scoped publish event hook registration by path without deleting unrelated hook files.
Docs:
  alpaca docs show event-hooks
---
Usage:
  alpaca event-hook test [--scope repo|user] --path <path> [--runner <command>]
Run one publish event hook with sample completed-event JSON to test its runner and observe any real side effects.
Options:
  --scope repo|user: Resolve the hook path from the repository root or configured user directory. Defaults to repo.
  --path <path>: Hook file path to test. Paths must stay inside the selected scope.
  --runner <command>: Runner command. Defaults from the file extension.
Notes:
  The sample event matches completed and all.
  The hook may perform real side effects during the test.
Docs:
  alpaca docs show event-hooks
---
Usage:
  alpaca service <enable|disable|restart|status|log>
Manage the background polling service.
Commands:
  enable   Install and start the AlpacaLoop background polling service so it watches registered repositories for runnable work.
  disable  Stop and remove the background polling service after current service work finishes, or immediately with --force.
  restart  Restart the background polling service after current service work finishes so it reloads configuration or package updates.
  status   Show background service state, registered repositories, active work, and whether the service is installed or running.
  log      Inspect background service logs.
Notes:
  Use a subcommand help page for option details.
Use `alpaca service <command> --help` for command-specific options.
---
Usage:
  alpaca service enable
Install and start the AlpacaLoop background polling service so it watches registered repositories for runnable work.
Notes:
  Stop it with service disable before using alpaca run.
  Linux and WSL2 require a working systemd user session (`systemctl --user`). WSL2 support assumes systemd is enabled.
  If the user service is unavailable on Linux/WSL2, use alpaca run as the foreground fallback.
---
Usage:
  alpaca service disable [--force]
Stop and remove the background polling service after current service work finishes, or immediately with --force.
Options:
  --force: Stop immediately without waiting for current service work to finish.
---
Usage:
  alpaca service restart [--force]
Restart the background polling service after current service work finishes so it reloads configuration or package updates.
Options:
  --force: Restart immediately without waiting for current service work to finish.
---
Usage:
  alpaca service status
Show background service state, registered repositories, active work, and whether the service is installed or running.
---
Usage:
  alpaca service log <show>
Inspect background service logs.
Commands:
  show  Show machine-local background service logs, with optional tailing for recent polling and worker-launch diagnostics.
Use `alpaca service log <command> --help` for command-specific options.
---
Usage:
  alpaca service log show [--tail <lines>]
Show machine-local background service logs, with optional tailing for recent polling and worker-launch diagnostics.
Options:
  --tail <lines>: Show only the last N lines.

SEE ALSO
git(1), gh(1)