@impulselab/hepha/README.md

Command-line interface for the Hepha platform.

# `hepha`

Command-line interface for creating and operating
[Hephaistos](https://hephaistos.impulselab.ai) sessions.

## Install

```bash
npm install --global @impulselab/hepha
```

Node.js 20 or newer is required.

## Quick start

```bash
hepha login
hepha whoami
hepha run "Add rate limiting to the public API" \
  --repo impulse-studio/hephaistos \
  --follow
```

Run `hepha help` to see all commands. The full API reference is available at
<https://hephaistos.impulselab.ai/api/v1/docs>.

## Authentication

`hepha login` uses device authorization and stores the resulting session in
`~/.hepha/config.json`.

For scripts and agents, use an API key:

```bash
export HEPHA_API_KEY="..."
hepha sessions list --json
```

`HEPHA_API_KEY` takes precedence over a stored login. `HEPHA_URL` can point the
CLI at another Hephaistos deployment. `HEPHA_TIMEOUT_MS` bounds one request;
`HEPHA_FOLLOW_MAX_OUTAGE_SECONDS` makes `--follow` give up that long after its
first failure, exiting with that failure. When unset, it waits for the platform to
come back.

## Exit codes

- `0`: completed successfully
- `1`: failed, killed, or abstained
- `2`: invalid CLI usage
- `3`: waiting for a human question or approval

## Agent skill

The package ships `skills/cli/SKILL.md`, an [Agent
Skill](https://agentskills.io) that teaches a coding agent what the platform
does and how to drive it: task types, the question cycle, the four guardrails,
then the commands, the exit codes and the mistakes that look right. Install the
package and the knowledge travels with it; `npm update` updates it.

```bash
npx @tanstack/intent@latest install       # writes discovery guidance once
npx @tanstack/intent@latest list --global # the CLI is usually installed globally
npx @tanstack/intent@latest load @impulselab/hepha#cli
```

Nothing runs on install: the skill is a file in the tarball and the tooling
reads it out of `node_modules`, never executing package code. Discovery is
opt-in per source, in the consuming project's `package.json`:

```json
{
  "intent": {
    "skills": ["@impulselab/hepha"],
    "exclude": ["@impulselab/hepha#experimental-*"]
  }
}
```

`intent.skills` is the package-level allowlist (`"*"` allows everything, `[]`
nothing), `intent.exclude` the finer control down to `package#skill`. That list
is the boundary; `intent hooks install` only nudges an editor to surface skill
loading, and must never be what decides a skill is safe to load.

### Maintaining it

`sources:` in the skill's frontmatter names the files it is distilled from.

```bash
pnpm --filter @impulselab/hepha exec intent validate skills   # blocking in CI
pnpm --filter @impulselab/hepha run skills:stale              # advisory
```

`.github/workflows/skills.yml` validates the skill on every PR that touches it,
and reports, without failing the build, when a PR edits a declared source
without touching the skill.