elias/claw-code
1
0
Fork 0
mirror of https://github.com/ultraworkers/claw-code.git synced 2026-04-24 05:00:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: USAGE.md sections for claw init (#142) and claw state (#139)

Browse Source 
Add two missing sections documenting the recently-fixed commands:

- **Initialize a repository**: Shows both text and JSON output modes for
  `claw init`. Explains that structured JSON fields (created[], updated[],
  skipped[], artifacts[]) allow claws to detect per-artifact state without
  substring-matching prose. Documents idempotency.

- **Inspect worker state**: Documents `claw state` and the prerequisite
  that a worker must have executed at least once. Includes the helpful error
  message and remediation hints (claw or claw prompt <text>) so users
  discovering the command for the first time see actionable guidance.

These sections complement the product fixes in #142 (init JSON structure)
and #139 (state error actionability) by documenting the contract from a
user perspective.

Related: ROADMAP #142 (structured init output), #139 (worker-state discoverability).
This commit is contained in:
YeonGyu-Kim 2026-04-21 18:28:21 +09:00
parent 541c5bb95d
commit e73b6a2364
1 changed files with 45 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
USAGE.md
View File

@ -52,6 +52,26 @@ cd rust
**Note:** Diagnostic verbs (`doctor`, `status`, `sandbox`, `version`) support `--output-format json` for machine-readable output. Invalid suffix arguments (e.g., `--json`) are now rejected at parse time rather than falling through to prompt dispatch.
### Initialize a repository
Set up a new repository with `.claw` config, `.claw.json`, `.gitignore` entries, and a `CLAUDE.md` guidance file:
```bash
cd /path/to/your/repo
./target/debug/claw init
```
Text mode (human-readable) shows artifact creation summary with project path and next steps. Idempotent — running multiple times in the same repo marks already-created files as "skipped".
JSON mode for scripting:
```bash
./target/debug/claw init --output-format json
```
Returns structured output with `project_path`, `created[]`, `updated[]`, `skipped[]` arrays (one per artifact), and `artifacts[]` carrying each file's `name` and machine-stable `status` tag. The legacy `message` field preserves backward compatibility.
**Why structured fields matter:** Claws can detect per-artifact state (`created` vs `updated` vs `skipped`) without substring-matching human prose. Use the `created[]`, `updated[]`, and `skipped[]` arrays for conditional follow-up logic (e.g., only commit if files were actually created, not just updated).
### Interactive REPL
```bash
@ -80,6 +100,31 @@ cd rust
./target/debug/claw --output-format json prompt "status"
```
### Inspect worker state
The `claw state` command reads `.claw/worker-state.json`, which is written by the interactive REPL or a one-shot prompt when a worker executes a task. This file contains the worker ID, session reference, model, and permission mode.
Prerequisite: You must run `claw` (interactive REPL) or `claw prompt <text>` at least once in the repository to produce the worker state file.
```bash
cd rust
./target/debug/claw state
```
JSON mode:
```bash
./target/debug/claw state --output-format json
```
If you run `claw state` before any worker has executed, you will see a helpful error:
```
error: no worker state file found at .claw/worker-state.json
Hint: worker state is written by the interactive REPL or a non-interactive prompt.
Run: claw # start the REPL (writes state on first turn)
Or: claw prompt <text> # run one non-interactive turn
Then rerun: claw state [--output-format json]
```
## Model and permission controls
```bash