Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hunvreus/heypi/llms.txt

Use this file to discover all available pages before exploring further.

The heypi CLI is a separate executable shipped with the npm package. It is not part of the runtime and is not invoked by createHeypi(). Use it for setup checks, provider diagnostics, database migrations, approval inspection, and scheduled job management.

​
Installation

npm install @hunvreus/heypi
# Then run via your package manager:
pnpm exec heypi check

​
Environment and database flags

Most provider commands load ./.env automatically when it exists. Pass --env <path> to load a different file. You can also supply tokens directly with command-specific flags, but using env files keeps your setup checks aligned with the app you are about to run. Commands that inspect or migrate the database need --db. Apps that omit store use the default SQLite database at <state.root>/heypi.db. From your app folder, pass that path explicitly: 
--db ./state/heypi.db

​
Commands

​
General

heypi check [--env .env] [--db ./state/heypi.db] [--runtime-root ./workspace]
heypi db check --db ./state/heypi.db
heypi db migrate --db ./state/heypi.db
heypi check verifies your Node version, checks for OPENAI_API_KEY, optionally validates the database, and checks that the runtime workspace directory exists.

​
Slack

heypi slack check [--env .env]
heypi slack manifest [--url https://host/slack/slack/events]
heypi slack channels [--env .env] [--private]
heypi slack env

​
Telegram

heypi telegram check [--env .env]
heypi telegram observe [--env .env] [--timeout 60]

​
Discord

heypi discord check [--env .env]
heypi discord observe [--env .env] [--timeout 60]
heypi discord channels [--env .env]
heypi discord invite --client-id <application-id>
heypi discord env

​
Admin

heypi admin link [--state ./state] [--url http://127.0.0.1:3000] [--pid <pid>] [--json]
See the Admin Panel guide for full details on how admin link works.

​
Approvals

heypi approvals list --db ./state/heypi.db [--json]
heypi approvals show <id> --db ./state/heypi.db [--json]

​
Jobs

heypi jobs list --db ./state/heypi.db [--agent <id>] [--json]
heypi jobs show <id> --db ./state/heypi.db [--agent <id>] [--json]
heypi jobs run <id> --db ./state/heypi.db [--agent <id>]
heypi jobs pause <id> --db ./state/heypi.db [--agent <id>]
heypi jobs resume <id> --db ./state/heypi.db [--agent <id>]

​
Discovery Commands

These commands help you find the channel and user IDs you need in your adapter config:
Waits for a delivered Telegram message, then prints the chat ID and a ready-to-paste targets snippet:
heypi telegram observe [--env .env] [--timeout 60]
Send /start to the bot or post in the target group while the command is waiting. Telegram cannot enumerate chats, so observe is the only way to discover a chat ID.
Lists Slack channel IDs visible to the bot and prints a targets snippet for each:
heypi slack channels [--env .env] [--private]
Use --private to include private channels (requires the appropriate Slack scope to be added to the bot).
Lists guild and channel IDs for all text channels visible to the bot:
heypi discord channels [--env .env]
Waits for a delivered Discord message and prints the guild, channel, and user IDs together with a targets snippet:
heypi discord observe [--env .env] [--timeout 60]
Send a DM to the bot or post in a channel it can read while the command is waiting.
Validates Slack credentials and prints the workspace/team identity and bot ID:
heypi slack check [--env .env]
Also reports whether SLACK_SIGNING_SECRET (HTTP mode) and SLACK_APP_TOKEN (Socket Mode) are present.

​
Database Migrations

heypi db migrate --db ./state/heypi.db
heypi db migrate applies the SQL migration files shipped in the package. Applied migration hashes are recorded in the database. If a migration file changes after it was applied, the command fails instead of replaying it.
After a migration file has been applied in production, treat it as immutable. Generate new migrations with Drizzle’s statement breakpoints rather than editing the baseline file.

​
Approvals and Jobs

Approval commands are read-only. Use the original chat provider to approve or deny requests so that the audit trail records the provider actor that made the decision.
jobs run marks the job due now but does not execute it directly. Execution happens on the next scheduler tick of a running Heypi app, which needs the app’s agent, adapters, runtime, and tools.
Use --agent <id> with job commands when the database contains more than one agent, or whenever you are mutating a job.

​
Document Conversion

heypi-convert-document is a separate binary shipped alongside the heypi CLI. It is used internally by the attachment processing pipeline and is not a subcommand of heypi. You do not call it directly in normal usage — it is invoked by the running Heypi process when document conversion is enabled via attachments.process. The binary requires Python 3 and either uv or MarkItDown installed in the Python environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us