Content
# spine233-agent-cli
Go 1.26 Local Spine Pro Agent CLI. Connect to
[`spine233-file-parser`](https://github.com/neko233-com/spine233-file-parser),
provides machine-readable CLI and stdio MCP.
## Principles
- Independent binary.
- Do not start, call, or depend on `Spine.exe` / `Spine.com`.
- `.spine`: raw-DEFLATE unpacking → temporary payload modification → repackaging.
- All write operations preview-first; never overwrite input.
- No network, account, or telemetry.
## Capabilities
- Detect `.spine`, `.skel`, Spine JSON.
- `.spine` lossless unpacking, inspection, and reserialization.
- Automatically parse `.spine` animation count, name, offset, and record boundary.
- Preview-first safe deletion of `.spine` animation table last item.
- Automatically parse `.spine` bone name, object offset, and original parent object token.
- Semantic parsing of rotate/translate/scale/shear, bone references, frames, values, and curves.
- Parse and re-time slot attachment switching keyframes.
- Fail-closed modification of animations by bone reference, timeline, keyframe, and channel.
- Direct positioning of animation records, fail-closed modification of big-endian float32 keyframes.
- Spine JSON deep analysis, reference verification, query, and patch.
- Spine JSON animation cloning, re-timing, and bone timeline replacement.
- Declarative rewriting of entire transform timeline, suitable for Codex to generate complete actions.
- Automatic generation of Codex editable complete recipe from existing animations.
- 22 stdio MCP tools.
## Installation
```bash
go install github.com/neko233-com/spine233-agent-cli/cmd/spine233-agent-cli@latest
```
## CLI
stdout only outputs JSON; error writes stderr JSON.
```bash
spine233-agent-cli detect --file hero.spine
spine233-agent-cli inspect --file hero.spine --output-dir .spine-diagnostics
spine233-agent-cli summarize --file hero.spine
spine233-agent-cli animations --file hero.spine
spine233-agent-cli bones --file hero.spine
spine233-agent-cli rotate-timelines --file hero.spine --animation attack
spine233-agent-cli transform-timelines --file hero.spine --animation attack
spine233-agent-cli slot-attachment-timelines --file alien.spine --animation death
spine233-agent-cli delete-last-project-animation \
--file hero-human.spine \
--animation walk
spine233-agent-cli scaffold-project-transform \
--file hero-human.spine \
--animation attack \
--bone-references 6,12 \
--timeline-types rotate,translate > attack-agent-recipe.json
```
Deletion of animations only allows the last item in the current directory and verifies the expected name; at least one animation is retained. Default preview, confirm and then `--apply` write to the same directory `*-agent.spine`, never overwriting input:
```bash
spine233-agent-cli delete-last-project-animation \
--file hero-human.spine \
--animation walk \
--apply
```
`--bone-references` and `--timeline-types` are optional; used to reduce the agent context of large projects. Codex workflow: generate recipe → modify `timelines[].keys` → preview → apply.
```bash
spine233-agent-cli rewrite-project-transform \
--recipe attack-agent-recipe.json
spine233-agent-cli rewrite-project-transform \
--recipe attack-agent-recipe.json \
--apply
spine233-agent-cli compare-project-transform \
--source hero-human.spine \
--source-animation attack \
--target hero-agent.spine \
--target-animation attack-agent
```
Compact batch programs can execute `set`, `add`, `multiply` by bone, keyframe, or frame range; `expectedMatches` is required to prevent accidental changes after project drift:
```bash
spine233-agent-cli program-project-transform \
--file hero-human.spine \
--animation attack \
--operations '[{"boneReferences":[6],"timeline":"rotate","channel":"value","keyIndices":[1,2],"mode":"add","operand":10,"expectedMatches":2}]'
```
Semantic modification of `.spine` rotate animation, default preview only:
```bash
spine233-agent-cli animate-project-transform --recipe demo/hero/agent-animation.json
spine233-agent-cli animate-project-transform \
--file hero-human.spine \
--animation attack \
--target-animation attack-agent \
--edits '[{"boneReference":6,"timeline":"rotate","keyIndex":1,"channel":"value","from":13.22,"to":24}]'
```
Entire timeline rewriting:
```bash
spine233-agent-cli rewrite-project-transform \
--file hero-human.spine \
--output hero-agent.spine \
--animation attack \
--target-animation attack-agent \
--timelines '[{"boneReference":6,"timeline":"translate","keys":[{"frame":0,"values":[-0.77,-1.89]},{"frame":5,"values":[8,-0.24]},{"frame":6,"values":[8.05,-2.44]},{"frame":12,"values":[-0.77,-1.89]}]}]' \
--apply
```
Rewriting maintains timeline and keyframe count; complete replacement of frame numbers and channel values, optional replacement of curves.
Confirm and output new project:
```bash
spine233-agent-cli animate-project-transform \
--recipe demo/hero/agent-animation.json \
--apply
spine233-agent-cli animate-project-transform \
--file hero-human.spine \
--output hero-agent.spine \
--animation attack \
--target-animation attack-agent \
--edits '[{"boneReference":6,"timeline":"rotate","keyIndex":1,"channel":"value","from":13.22,"to":24}]' \
--apply
```
`boneReference`, `timeline`, `keyIndex`, `channel`, `from` any mismatch fails, avoiding layout or Agent plan drift causing accidental changes. Rotate-specific and original float32 mode continue to be compatible. `channel:"frame"` can directly re-time; output will verify each timeline frame number strictly increasing. `channel:"curve.x.0"` etc. can modify stored channel curve control values.
Spine JSON operations:
```bash
spine233-agent-cli analyze --file hero.json
spine233-agent-cli validate --file hero.json
spine233-agent-cli query --file hero.json --pointer /animations/walk
spine233-agent-cli patch \
--file hero.json \
--operations '[{"op":"replace","path":"/bones/1/name","value":"arm-new"}]'
```
## Agent / MCP
```bash
spine233-agent-cli serve
```
Codex:
```toml
[mcp_servers.spine233]
command = "spine233-agent-cli"
args = ["serve"]
```
MCP Tools:
| Tool | Purpose |
| --- | --- |
| `spine_detect` | Detect files |
| `spine_summarize` | Compact summary |
| `spine_inspect_project` | `.spine` unpacking diagnostics |
| `spine_list_project_animations` | Directly list `.spine` animation directory |
| `spine_delete_last_project_animation` | Preview or delete animation table last item |
| `spine_list_project_bones` | Directly list `.spine` bone directory |
| `spine_list_project_rotate_timelines` | Semantically list rotate timelines |
| `spine_list_project_transform_timelines` | List bone transform timelines |
| `spine_list_project_slot_attachment_timelines` | List attachment switching keyframes |
| `spine_compare_project_transform_animation` | Verify human/agent animation name and semantic differences |
| `spine_build_project_transform_recipe` | Generate complete or filtered recipe from existing animations |
| `spine_program_project_transform_animation` | Batch generate precise edits protected by match count |
| `spine_patch_project_animation` | Directly modify `.spine` animation keyframes |
| `spine_patch_project_rotate` | Semantically modify rotate keyframes |
| `spine_patch_project_transform` | Modify bone transform keyframes |
| `spine_patch_project_slot_attachment` | Re-time existing attachment keyframes |
| `spine_rewrite_project_transform_animation` | Declarative rewriting of entire transform timeline |
| `spine_query_json` | JSON Pointer query |
| `spine_patch_json` | JSON Patch |
| `spine_analyze_json` | Deep capability list |
| `spine_validate_json` | Reference verification |
| `spine_clone_animation` | JSON animation generation |
## Demo
`demo/alien`, `demo/hero`, `demo/raptor` each retain:
- `<character>-human.spine`: Official manual Pro project.
- `<character>-agent.spine`: This CLI directly generates project.
- `agent-animation.json`: Auditable generated recipe.
- Official images, exported resources, and licenses.
## Development
```bash
gofmt -w .
go test ./...
go vet ./...
go build -o bin/spine233-agent-cli ./cmd/spine233-agent-cli
```
## License
MIT. Spine is a trademark of Esoteric Software LLC. Demo assets comply with directory licenses.
