# Domain CLI

> Use when changing, extending, testing, or reviewing the Bun-backed Paw CLI package and its generated agent skills.

- Skill: `octaviantocan/domain-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add octaviantocan/domain-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/octaviantocan/domain-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: octaviantocan (https://skillmd.com/u/octaviantocan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/octaviantocan/domain-cli

---


<!-- AUTO-GENERATED by skill-gen -- DO NOT EDIT -->
<!-- Source: packages/paw-cli/src/Skills/Fragments.ts -->

# domain-cli

Use this skill before changing the Paw CLI package. The CLI is a standalone Bun-first Effect v4 package at `packages/paw-cli`; feature-owned commands are added only when the owning feature needs them.

## Before Editing

- Load `code-quality`, `domain-cli`, and `domain-effect` before writing or reviewing CLI code.
- Check `backend/vendor/effect-smol` for any Effect v4 API you are about to use; do not infer current APIs from older Effect docs or memory.
- Treat Bun runtime services, Effect v4 idioms, schema-backed boundaries, and contract-only docstrings as first-pass requirements, not cleanup work after scaffolding.

## Package Shape

```text
packages/paw-cli/
|-- src/
|   |-- Main.ts
|   |-- Cli.ts
|   |-- Commands.ts
|   |-- Helpers/
|   |-- Infrastructure/
|   |-- Modules/<Name>/
|   `-- Skills/Fragments.ts
`-- test/
    |-- unit/
    |-- integration/
    `-- fixtures/
```

## Current Command Surface

| Command | Aliases | Summary |
| --- | --- | --- |
| `paw doctor` | - | Check local Paw CLI readiness |
| `paw context` | whoami | Print the active CLI context without secrets |
| `paw completions <shell>` | - | Generate shell completions |

## Rules

- Keep `effect`, `@effect/platform-bun`, and `@effect/vitest` on the same latest verified v4 beta in `packages/paw-cli/package.json`.
- Use Bun runtime services for CLI execution; do not add `@effect/platform-node` or `node:*` imports to `packages/paw-cli/src`.
- Keep shared runtime services under `src/Infrastructure/`; feature modules should not import shared services from each other.
- Keep command modules under `src/Modules/<Name>/` with `Command.ts`, plus `Domain.ts` and focused helpers only when the command needs them.
- Register command modules in `src/Commands.ts`; do not create placeholder command groups for future product ideas.
- Feature-owned CLI commands must target real feature contracts. For 006 provider sessions, use `paw sessions ...` against session/Workspace/provider bindings; do not add `paw agents ...` until a real agent-management registry exists.
- CLI commands that call backend-ts should use public HTTP/RPC clients from `api-core`/`rpc-core`; normal CLI commands must not import provider adapters or `harness` internals.
- Keep command metadata next to the command implementation and make generated skills read from that metadata.
- Define schemas for external input and public output before adding ad hoc parsing or rendering code.
- Use `Schema.TaggedErrorClass` from `src/Helpers/Errors.ts` for expected public CLI failures and map failures to the public exit-code contract.
- Use `src/Helpers/Output.ts` for `human`, `json`, and `plain` rendering; JSON output must encode through a declared Effect `Schema` before stdout.
- Prefer JSON Schema documents from Effect `Schema.toJsonSchemaDocument` for CLI contracts; OpenAPI belongs to `HttpApi`, not this CLI package.
- Use `src/Helpers/Config.ts` for profile, state-root, TOML, and no-secret config behavior; environment-backed settings go through Effect `Config` descriptors and deterministic `ConfigProvider` tests.
- Preserve explicit Paw config precedence and source labels: flags, env, project TOML, profile TOML, user TOML, defaults.
- Treat first-slice helpers like `InputSource.ts`, `writeProfileConfig()`, and unused error tags as tested policy helpers until a feature-owned command needs them.
- Use `@effect/vitest` for tests that directly exercise Effect values or services; plain Vitest is fine for process integration and pure synchronous assertions.
- Remove old Python CLI references instead of bridging, shelling out, or maintaining compatibility shims.

## Add A Command Group

1. Create `packages/paw-cli/src/Modules/<Name>/Command.ts` and a `Domain.ts` when the command needs domain types or services.
2. Define command metadata with `name`, `summary`, `description`, `owner`, flags, examples, output modes, structured output contracts, and exit codes.
3. Define schemas for external input, public JSON output, and expected errors before command rendering or parsing code.
4. Build the command with `effect/unstable/cli` primitives and Effect handlers.
5. Register the module in `packages/paw-cli/src/Commands.ts`.
6. Add unit and integration tests under `packages/paw-cli/test/`, including ConfigProvider tests for environment-backed settings.
7. Run the CLI checks and regenerate skills.

## Skill Generation

`packages/paw-cli/src/Skills/Fragments.ts` exports dynamic fragments for `paw` and `domain-cli`. `packages/ci/skill-gen` loads those fragments and merges them with normal `//<skill-gen>` source markers, so generated skills stay aligned with the command registry.

```bash
bun run skill-gen:generate
bun run skill-gen:check
bun run skill-gen:e2e-test
```

## Required Checks

```bash
bun run --filter @pawrrtal/cli typecheck
bun run --filter @pawrrtal/cli test
bun run --filter @pawrrtal/cli check
bun run skill-gen:check
just paw-cli-check
```