Skip to content

cli.md

Latest commit

 

History

History
254 lines (192 loc) · 8.48 KB

cli.md

File metadata and controls

254 lines (192 loc) · 8.48 KB
Raw

CLI reference

yskill runs and resumes skill workflows. It owns run logs, validates responses, executes commands, and starts the skill workflow. It comes with each language package.

helper install

yskill helper install
  [--language typescript|python|rust|go]
  [--agent auto|cursor,codex,claude-code]
  [--root repository]
  [--dry-run]
  [--yes]

Explicitly installs the optional developer helper. Package installation alone does not create skills or adapters. The command detects the repository, language, and installed coding agents. It shows every proposed change before it writes. It asks for confirmation unless --yes is set. It installs and tests skills/yield-workflow-builder, registers the selected adapters, and verifies them.

The installer stores local state under ignored .yield/. It refuses paths outside the project root, symlink escapes, existing destinations, and user-owned adapter files. TypeScript and Python use the current directory when no Git or local-runtime root exists. Go and Rust require their project-local runtime. --root overrides inference.

The installer can change only these repository locations:

  • .yield/.gitignore and .yield/bootstrap.json
  • .yield/bin/yskill for Go and Rust
  • skills/yield-workflow-builder/ and its language dependency lockfile
  • selected generated agent adapter paths

The TypeScript dependency install also creates ignored node_modules/ content. The installer runs only the dependency preparation command shown in the plan, doctor --test, and adapter registration. It does not use install hooks.

yskill bootstrap is a compatibility alias. The npm create @operatorstack/yield@latest initializer calls the same installer.

init

yskill init <directory> --description "What it does and when to use it"
  [--language typescript|python|go|rust]

Scaffolds a new skill workflow or adds a Yield program beside an existing prose skill. Generated dependencies are pinned to the installed yskill version. New skills require a real trigger-oriented description. Existing SKILL.md files are preserved and validated.

register

yskill register <skill-directory> [--agent cursor,codex,...|auto]
  [--root repository]

Writes generated, project-local SKILL.md adapters for the selected coding agents. Without --agent, Yield detects verified agents. Explicit IDs work for every entry printed by yskill agents. Workflow code, dependencies, fixtures, and run state remain in the canonical skill directory.

Registration updates only adapters previously generated from the same source. It refuses user-owned files, workflows outside the repository, and canonical workflows stored inside a selected agent's discovery directory. For TypeScript and Python outside Git, the current directory is the project root and the workflow must be contained within it. --root overrides inference.

agents

yskill agents

Lists agent IDs, project skill directories, detection state, and whether each entry is verified or registry-supported.

doctor

yskill doctor <skill-directory> [--agent cursor,codex,...|auto]
  [--root repository] [--test]

Checks the canonical skill workflow and package launcher. --test also runs the workflow against fixtures/responses.json without leaving a run journal. Adapter checks run only when --agent is supplied, and all adapter problems are reported together. For TypeScript and Python outside Git, adapter checks use the current directory when the workflow is contained within it.

version

yskill --version
yskill version

Prints the runtime version and platform.

run

yskill run <skill-directory> [--input input.json] [--experiment experiment.json]

Starts a run and prints the first unanswered operation. The run is stored under the skill's .yield/runs/ directory. Optional experiment metadata uses the closed experiment_id, cohort_id, variant_id, role, baseline_variant_id, and parent_skill_version fields. It is observation metadata and cannot change replay or the workflow result.

resume

yskill resume <run-id> --response response.json [--skill directory]

Validates one response and prints the next operation or terminal outcome. --accept-new-digest explicitly rebinds a saved run after intentional skill source changes; do not use it to hide accidental drift.

resume is the file-based interface for CI and audit tooling. For normal agent use, prefer respond.

respond

yskill respond <run-id> --value <answer> [--skill directory]
yskill respond <run-id> --result-json '<json>' [--skill directory]
yskill respond <run-id> --result-json - [--skill directory]

Reads the pending operation, builds the response envelope, validates the result, and advances the run as one locked transition. --value answers an ask_user operation. --result-json supplies a structured agent result; - reads JSON from standard input. Completed results are printed in full.

register-all

yskill register-all <skills-directory> --agent cursor,codex
  [--root repository] [--dry-run] [--prune]

Registers every immediate skill workflow in one directory. It checks all names and destinations before writing. --prune removes only obsolete adapters generated from that workflow directory. Agent-facing names must be unique, and every workflow must resolve to the same project root.

inspect

yskill inspect [run-id] [--skill directory]

Without a run ID, lists saved runs. With an ID, prints the append-only event log.

replay

yskill replay <run-id> [--skill directory]

Re-executes the program from the log and verifies that recorded operations lead to the same frontier. Operation drift fails loudly.

receipt

yskill receipt <run-id> [--skill directory]
yskill receipt materialize <run-id> [--skill directory]
yskill receipt materialize --all [--skill directory]

Derives a portable receipt from one exact journal prefix. The first form prints without changing local state. materialize writes the immutable object and updates the run reference. New foreground runs materialize automatically.

outbox

yskill outbox enqueue <run-id> --sink <id> [--skill directory]
yskill outbox enqueue --all-terminal --sink <id> [--skill directory]
yskill outbox deliver --sink <id> [--skill directory] -- <argv...>
yskill outbox status [--sink <id>] [--skill directory]
yskill outbox retry <receipt-digest> --sink <id> [--skill directory]
yskill outbox retry --failed|--unknown --sink <id> [--skill directory]

Queues and delivers materialized receipts outside foreground execution. Yield runs the sink argv directly and sends one receipt on standard input. Delivery is idempotent by receipt digest, retryable, order-independent, and protected by a per-digest lock. See portable run receipts.

report

yskill report <skill-directory> [--from RFC3339] [--to RFC3339]
  [--experiment id] [--open-age-threshold duration] [--format table|json]

Aggregates latest local receipts by lifecycle, terminal disposition, operation timing, rejection and requirement outcome, runtime and source identity, and experiment variant. It makes no causal, winner, or activation claim.

test

yskill test <skill-directory> [--keep-run]

Uses fixtures/responses.json for ask_user and agent_task operations. run_command operations still execute for real. The command succeeds only when the program reaches completed. Test journals are temporary unless --keep-run is supplied. Optional fixtures/test.json setup, per-response, and teardown commands use argv arrays and never run through a shell.

{
  "version": 1,
  "setup": [["node", "fixtures/setup.mjs"]],
  "after_response": {
    "approve": [["node", "fixtures/apply-approval.mjs"]]
  },
  "teardown": [["node", "fixtures/teardown.mjs"]]
}

Each after_response command receives that fixture response as JSON on standard input. Hooks run only during yskill test.

setup runs before the first workflow step. after_response runs after the named fixture response is accepted. teardown always runs after success or failure. Every hook receives YIELD_FIXTURE=1. This keeps test-only effects out of live workflows.

prune

yskill prune <skill-directory> --older-than 720h
  [--keep-last 10] [--dry-run]

Removes old terminal runs. Active runs are never selected. Before deletion, Yield proves that the terminal receipt exists or can be materialized. Receipt objects and outbox entries are not pruned.