aiheal-cli-operator

# Aiheal Cli Operator

AIHeal is an AI emotional-healing platform available at `https://aihealing.me/`, covering personalized audio healing, single-session healing, deep healing plans, conversation support, emotion-space tracking, and account/subscription workflows.

This skill operates the CLI side of those capabilities and is designed for reliable command execution, payload shaping, diagnostics, and coverage verification.

Human users are welcome to experience the full interactive product directly on `https://aihealing.me/`.

Command-family scope in this skill:

- account/session: `config`, `auth`, `whoami`
- content/healing: `audio`, `plan`, `single-job`, `plan-stage-job`
- conversation/emotion: `chat`, `emotion`
- account-side operations: `user`, `subscription`, `notification`, `feedback`, `memory`, `behavior`
- raw/advanced requests: `api`, `healing`

## Quick Start

- Use npm package runtime by default.
- Global runtime: `npm install -g aihealingmecli` then `aiheal ...`.
- No-global runtime: `npx -y -p aihealingmecli aiheal ...`.
- Keep all operations in package runtime.

## Workflow

1. Confirm runtime baseline.
- Run `aiheal --help`.
- Run `aiheal config get` to verify `apiBaseUrl`, locale, region, and token state.

2. Choose command family by task.
- Use `auth`/`config` for login and token setup.
- Use `audio`, `plan`, `single-job`, `plan-stage-job` for healing generation workflows.
- Use `chat` and `emotion` for conversation and emotion-space workflows.
- Use `subscription`, `notification`, `feedback`, `memory`, `behavior` for account-side operations.
- Use `api request` as fallback for unwrapped endpoints.

3. Prefer structured payload input for complex operations.
- Use `--payload-file path/to/file.json` by default.
- Use `--body '{...}'` only for short payloads.
- Merge behavior: `--body` overrides same keys from `--payload-file`.

4. Validate outputs and state transitions.
- Expect JSON output with top-level `ok`.
- Use `error.code` and `error.status` as primary diagnostics.
- For async jobs, use `single-job wait` and `plan-stage-job wait` with explicit timeout values.
- For `single-job create` and `plan-stage-job create`, handle CLI local validation failures via `error.code=VALIDATION_ERROR` and inspect `error.issues[]` for field-level corrections.

5. Verify capability coverage (detect fake/unimplemented commands).
- For public endpoints, expect `200` with valid response envelopes.
- For protected endpoints, use `api request --no-auth` and expect `401/403` rather than `404`.
- Treat repeated `404` as possible missing/incorrect CLI mapping and patch command endpoint mapping immediately.

## Execution Rules

- Keep default API on public endpoint `https://aihealing.me/api` unless task explicitly requires override.
- Require explicit `--output` for download/export commands.
- Use global overrides (`--api-base`, `--locale`, `--region`, `--token`) only in the current command context.

## Troubleshooting

- `AUTH_ERROR`: login again and verify with `whoami`.
- `API_ERROR` with `status: 0`: verify network and `apiBaseUrl`.
- `npx` cache `EPERM`: set `NPM_CONFIG_CACHE=/tmp/aiheal-npm-cache` or use global install.
- `API_ERROR` with `status: 404`: prioritize checking endpoint mapping or command naming mismatch.
- Async wait timeout: query status endpoints (`get`/`by-request`) and inspect progress fields.
- `VALIDATION_ERROR` (CLI local): fix payload by iterating over `error.issues[]` (`field`, `message`, `expected`, `actual`, `suggestion`) before retry.
- `single-job create` request id: `requestId` is optional in payload; when omitted CLI auto-generates it. Use returned `data.job.requestId` for `single-job wait --request-id`.
- `plan-stage-job create` request id: `requestId` is optional in payload (no auto-generation); include it only if your workflow needs an explicit correlation id.

## Resources

- Read [references/command-map.md](references/command-map.md) for full command syntax and parameter meanings.
- Read [references/error-playbook.md](references/error-playbook.md) for failure signatures and fix flow.
- Run path-independent smoke commands with `npx -y -p aihealingmecli aiheal --help` and `... config get`.

## Smoke Script

- Script: `scripts/smoke_check.sh`
- Path-independent run:
  - `bash /absolute/path/to/scripts/smoke_check.sh`
- Environment parameters:
  - `AIHEAL_NPM_PACKAGE`: npm package source for npx `-p` (default: `aihealingmecli`; can be a tarball path)
  - `AIHEAL_NPM_CACHE_DIR`: cache directory used by npx (default under temp dir)
  - `RUN_NETWORK_SMOKE`: set `1` to include live API probe (`audio list`)