hepha

Command-line interface for creating and operating Hephaistos sessions.

Install

npm install --global @impulselab/hepha

Node.js 20 or newer is required.

Quick start

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:

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 — 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 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.

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:

{
  "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.

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.