Skip to content

cli_handbook.md

Latest commit

 

History

History
331 lines (231 loc) · 10.3 KB

cli_handbook.md

File metadata and controls

331 lines (231 loc) · 10.3 KB
Raw

ResearchSpec CLI Handbook

Generated from the typed public CLI catalog. Do not edit this file by hand.

This handbook describes the static command surface. It does not expose a live workflow frontier or authorize a workspace write.

Discovery boundary

  1. Run researchspec --help to discover the public commands.
  2. Run researchspec <command> --help (or the relevant plugin subcommand help) to inspect syntax and options.
  3. For a current workspace action, run researchspec status --json, select a returned action selector, and read researchspec instructions <selector> --json.
  4. Follow the action descriptor's semantic input, availability basis, execution policy and returned next_selectors; static help never supplies those facts.

Global options

Option Purpose
--cwd <path> project working directory
--workspace <path> explicit researchspec workspace
--json emit one machine-readable envelope
--dry-run plan writes without modifying files
--force refresh manifest-owned generated files
--yes skip low-risk confirmations
--quiet suppress nonessential human output

Action selector families

A valid selector shape does not imply that the action is available in the current workspace.

Family Accepted forms
subflow subflow:tpl-<id>
subflow:sf-<id>
subflow:sf-<instance>/<node>
obligation obligation:sf-<instance>/<id>
gate gate:<id>
gate:sf-<instance>/<id>
completion completion:sf-<instance>/<id>
case-action case-action:<id>
patch patch:<id>
change change:<id>
work work:sf-<instance>/<node>
transition transition:sf-<instance>/<node>

Bootstrap

researchspec init [path]

Initialize or safely extend a ResearchSpec workspace

  • Workspace: none
  • Static effect: write
  • Related commands: update, status
Command option Required Purpose
--tools <ids> no all, none, or comma-separated tool IDs
--profile <mode> no adaptive or strict runtime profile

researchspec update [path]

Refresh selected generated agent files

  • Workspace: required
  • Static effect: write
  • Related commands: init, status, doctor
Command option Required Purpose
--tools <ids> no refresh/add a tool subset
--migrate-runtime no migrate a valid Schema 0.2 runtime to adaptive
--rollback <migration-id> no restore the pre-migration runtime captured by a migration
--expected-plan-sha256 <hash> no bind execution to the previewed migration or rollback plan

Control plane

researchspec status

Show current run and pending-item status

  • Workspace: required
  • Static effect: read
  • Related commands: instructions, show, list

researchspec instructions <selector>

Show dynamic instructions for a runtime action selector

  • Workspace: required
  • Static effect: read
  • Related commands: status, start, submit, advance, decide

researchspec start <subflow>

Atomically start a confirmed template or delegated child subflow

  • Workspace: required
  • Static effect: write
  • Related commands: status, instructions
Command option Required Purpose
--input <start.json> yes strict semantic Start JSON
--actor-kind <kind> yes human, agent, or script
--actor-name <name> yes Start requester name
--confirmed-by <name> no human who confirmed an external route
--expected-action-basis-sha256 <hash> no bind execution to the current action descriptor
--expected-plan-sha256 <hash> no bind execution to the previewed Start plan

researchspec submit <runtime-item>

Submit a runtime candidate, attempt, evidence, resolution, patch, or confirmed Gate verdict

  • Workspace: required
  • Static effect: write
  • Related commands: status, instructions, check
Command option Required Purpose
--input <payload.json> yes strict semantic submission JSON
--actor-kind <kind> yes human, agent, script, converter, or validator
--actor-name <name> yes artifact producer name
--confirmed-by <name> no human who confirmed a Gate verdict
--expected-action-basis-sha256 <hash> no bind execution to the current action descriptor
--expected-sha256 <hash> no bind execution to the previewed candidate SHA-256
--expected-plan-sha256 <hash> no bind execution to the previewed submission plan

researchspec advance <transition>

Complete or advance one currently authorized runtime action

  • Workspace: required
  • Static effect: write
  • Related commands: status, instructions
Command option Required Purpose
--actor-kind <kind> yes agent or script
--actor-name <name> yes action executor name
--expected-action-basis-sha256 <hash> no bind execution to the current action descriptor
--expected-plan-sha256 <hash> no bind execution to the previewed action plan

Inspection

researchspec check [target]

Check all, contracts, runtime, artifacts, tools, plugins, or literature-adapters

  • Workspace: required
  • Static effect: read
  • Related commands: status, doctor, show
Command option Required Purpose
--strict no treat warnings as failures

researchspec list [type]

List paginated runtime collections

  • Workspace: required
  • Static effect: read
  • Related commands: show, status
Command option Required Purpose
--limit <count> no page size from 1 to 50
--cursor <cursor> no opaque cursor returned by the prior page

researchspec show <item>

Show a canonical or globally unique item

  • Workspace: required
  • Static effect: read
  • Related commands: list, check

Recovery

researchspec doctor

Diagnose runtime damage or apply one plan-bound deterministic repair

  • Workspace: required
  • Static effect: conditional-write
  • Related commands: check, status
Command option Required Purpose
--repair <finding-id> no preview or apply a deterministically repairable finding
--expected-plan-sha256 <hash> no bind execution to the previewed Doctor repair plan

Context

researchspec handoff

Render the current handoff view

  • Workspace: required
  • Static effect: conditional-write
  • Related commands: pack, status
Command option Required Purpose
--stdout no print without writing
--out <path> no output path

researchspec pack

Create a deterministic context bundle

  • Workspace: required
  • Static effect: write
  • Related commands: handoff, check
Command option Required Purpose
--out <path> no output ZIP path
--include-artifacts no include safe registered artifacts

Governance

researchspec propose <change-id>

Create a validated pending contract change

  • Workspace: required
  • Static effect: write
  • Related commands: decide, show, check
Command option Required Purpose
--input <payload.json> yes strict semantic proposal JSON
--actor-kind <kind> yes human or agent
--actor-name <name> yes proposal author name
--expected-action-basis-sha256 <hash> no bind execution to the current action descriptor
--expected-plan-sha256 <hash> no bind execution to the previewed proposal plan

researchspec decide [item]

Resolve a pending human decision

  • Workspace: required
  • Static effect: write
  • Related commands: instructions, show, archive
Command option Required Purpose
--decision <choice> no accept, reject, or postpone
--actor-name <name> no human actor name
--reason <text> no decision rationale
--expected-action-basis-sha256 <hash> no bind execution to the current action descriptor
--expected-plan-sha256 <hash> no bind execution to the previewed decision plan

researchspec archive [item]

Archive a resolved change or draft patch

  • Workspace: required
  • Static effect: write
  • Related commands: list, show

Domain Skills

researchspec plugin

Inspect and manage bundled domain Skill plugins

  • Workspace: optional
  • Static effect: conditional-write
  • Related commands: plugin list, plugin show, plugin install, plugin uninstall, plugin update, plugin instructions

researchspec plugin list

List bundled domain Skill plugins

  • Workspace: optional
  • Static effect: read
  • Related commands: plugin show, plugin install
Command option Required Purpose
--installed no show only workspace-selected plugins
--summary no emit compact discovery metadata

researchspec plugin show <plugin-id>

Show bundled plugin metadata and provenance

  • Workspace: optional
  • Static effect: read
  • Related commands: plugin list, plugin install
Command option Required Purpose
--summary no emit compact Skill descriptions without full provenance

researchspec plugin install <plugin-ids...>

Select and project plugins into the current workspace

  • Workspace: required
  • Static effect: write
  • Related commands: plugin list, plugin show, plugin uninstall, plugin update
Command option Required Purpose
--expected-plan-sha256 <hash> no bind execution to the previewed plugin install plan
--summary no emit aggregate write-plan impact

researchspec plugin uninstall <plugin-ids...>

Remove selected plugins from the current workspace

  • Workspace: required
  • Static effect: write
  • Related commands: plugin list, plugin install

researchspec plugin update [plugin-ids...]

Refresh selected plugins, or all when IDs are omitted

  • Workspace: required
  • Static effect: write
  • Related commands: plugin list, plugin show

researchspec plugin instructions <skill-id>

Read an installed hash-clean plugin Skill for immediate advisory use

  • Workspace: required
  • Static effect: read
  • Related commands: plugin list, plugin show