@typescape-ai/cli

Typescape CLI — agent-first review, finding, and rules workflows for Markdown.

Requirements

• Bun 1.3.10+

Installation

# Global install with Bun
bun add -g @typescape-ai/cli

# Or install in a project with Bun
bun add -D @typescape-ai/cli

Run without installing:

bunx @typescape-ai/cli

Quick Start

1. Initialize config in your repo:

typescape init

2. Set your API token:

export TYPESCAPE_API_KEY=your-token-here

3. Fetch the canonical rules bundle for the content you are about to review:

typescape rules get --properties '{"doc_type":"procedure"}'

rules get --format text now prepends a metadata block with the bundle compiled_hash, freshness, and applicability basis. Use plain --format text for the canonical human/agent-readable bundle, or --format structured / --format json for machine-oriented payloads.

4. Create a review:

typescape review create --file docs/README.md --reviewer [email protected]

5. Optionally request a fast advisory pass:

typescape rules check --file docs/README.md --properties '{"doc_type":"procedure"}'

rules check is advisory. The canonical loop is:

1. typescape rules get
2. the agent reads the draft and reasons over it
3. typescape finding create

Its exit codes are still useful for automation: 0 means the advisory pass ran with no blocking signals, 1 means it returned blocking signals, 2 is validation, 3 is network/auth, and 4 is a server error.

6. Record findings in plain language:

typescape finding create --review sess_abc123 --body "Never mention supplements in patient-facing copy."

7. Export feedback:

typescape review export --review rev_xxx

review export defaults to the canonical export.v2 contract. Explicit --schema v1 runtime requests are retired; use versioned views like response_matrix.v1 only when you intentionally need that bounded compatibility shape.

Commands

Review Management

| Command | Description | | ------------------ | ------------------------------------------------------------ | | review create | Create a new review | | review get | Get review details | | review list | List reviews with filters | | review export | Export review feedback as canonical export.v2 JSON | | review status | Get policy verdict for a review | | review close | Close a review | | review supersede | Create a new content-review revision from an existing review |

Findings & Comments

| Command | Description | | ------------------ | ---------------------------------------------------- | | finding create | Record a plain-language finding on a review or block | | finding comment | Post a reply to an existing finding | | finding list | List findings for a review | | finding resolve | Resolve a finding | | finding decision | Record a decision on a finding | | finding evidence | Attach evidence to a finding |

Rules

| Command | Description | | ----------------- | ------------------------------------------------------------ | | rules list | List applicable rules | | rules get | Get the canonical compiled rules bundle for agent reasoning | | rules check | Request an optional server-side advisory pass | | rules documents | List canonical rule-document truth | | rules import | Import markdown into a draft rule review | | rules publish | Publish a draft rule review; it is not live until activation | | rules revise | Create or revise a working draft for a rule review | | rules deprecate | Deprecate a published rule review | | rules candidate | Create, inspect, and transition release candidates | | rules dashboard | Inspect supplemental rule diagnostics | | rules signal | Submit, inspect, and triage governance signals | | coverage | Check section coverage against active rules |

Review & Approval

| Command | Description | | -------------------- | ----------------------------------------- | | approval request | Request approval from specified approvers | | approval decide | Record an approval decision | | review-ref get | Get review reference detail and lineage | | review-ref create | Create a stable review reference | | review-ref resolve | Resolve a review ref to its current head | | review-ref advance | Advance a review ref to a new head | | proposed-changes | Manage proposed changes | | checks run | Run quality checks (DocLint) | | search | Search reviews by title and file path | | verify export | Validate an export against the schema |

Orchestration & Collections

| Command | Description | | ------------------- | ---------------------------------------------------- | | repo list | List connected repositories | | repo connect | Connect a repository by Git URL | | repo branches | List branches for a connected repository | | project create | Create a new upload-backed project | | project list | List projects | | project get | Get project detail | | project update | Update project metadata | | project delete | Start project deletion | | project move | Declare a project file-path move | | project upload | Upload files into a project batch | | template create | Create a reusable review template | | template list | List review templates | | template get | Get template detail | | review-set create | Create a multi-file review set | | review-set list | List review sets | | review-set get | Get review set overview | | review-set update | Update review set title or lifecycle state | | review-set export | Export a review set using canonical schema=v2 | | review-set status | Evaluate aggregate review-set policy status | | collection create | Create a new collection | | collection add | Add reviews to a collection | | collection get | Get one collection with member reviews | | collection list | List collections | | collection update | Update collection metadata or archive state | | collection delete | Archive a collection via the canonical PATCH surface |

Auth & Configuration

| Command | Description | | ----------------- | ------------------------------------------- | | init | Create .typescape/config.yaml | | config validate | Validate config and show effective settings | | token generate | Generate a new API token | | auth login | Authenticate with the Typescape server | | smoke-test | End-to-end sanity check | | anchors | Inspect block anchors for a file | | ids | Generate Typescape IDs |

Configuration

Create .typescape/config.yaml:

version: 1
server:
  base_url: https://your-typescape-instance.com

Set TYPESCAPE_API_KEY environment variable with your operator token.

The old top-level guidelines, gci, and advisory command families are removed. New automation should use the rules command family directly, including rules signal for governance-signal workflows. Explicit export.v1 runtime requests are retired; first-party exports default to export.v2, while response_matrix.v1 remains a bounded compatibility view.

License

MIT