UI Potion Logo UI Potion
Home / Potion Kit

Potion Kit

CLI to build websites with Harold and UI Potion: static sites with Handlebars, Markdown, and SCSS only. Chat with the AI to design and build your site; the model uses the UI Potion catalog and Harold conventions and can only suggest components from real specs.

Note: Potion Kit is actively developed. For the best experience we recommend the newest OpenAI or Anthropic models; for a good cheaper option, use Kimi K2.5. Extensive use consumes API tokens and costs depend on your provider's pricing. By using the tool you accept it as-is; only you decide whether and how much to use it. We hope you enjoy building with it.

Commands

  • potion-kit chat — Interactive chat.
  • potion-kit chat "message" — Send one message and exit (one-shot).
  • potion-kit clear — Clear chat state for this project (history, summary cache, and event trace ledger).
  • potion-kit or potion-kit --help — Show usage and available commands. Unknown commands also show help and do not call the API.

Install & Run

Use Potion Kit as an installed CLI from any directory where you have a .env with your LLM API key. No need to clone the repo.

Install

Option A — npx (no install):

npx potion-kit chat

Option B — global install:

npm install -g potion-kit
potion-kit chat

Run in your project

  1. Go to the directory where you want to work (new site or existing project). It can be an empty folder.
  2. Create a .env file with your LLM provider and API key. Minimal contents:
POTION_KIT_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

For Anthropic use POTION_KIT_PROVIDER=anthropic and ANTHROPIC_API_KEY=.... For Moonshot use POTION_KIT_PROVIDER=moonshot and MOONSHOT_API_KEY=.... See the Potion Kit README for all options and security notes.

  1. Run Potion Kit from that same directory:
npx potion-kit chat
# or, if installed globally:
potion-kit chat

The tool reads .env from the current working directory, so always run potion-kit from the directory that contains your .env.

Usage Examples

Interactive chat (recommended):

cd my-project
npx potion-kit chat

Type your message at the You: prompt, press Enter; the model replies. Type exit, quit, or q (or Ctrl+C) to quit. Your conversation is saved for the next run.

One-shot (single message then exit):

npx potion-kit chat "I want a blog with a header and footer"
npx potion-kit chat "Add the navbar potion to the layout"

Start a new conversation:

npx potion-kit clear
npx potion-kit chat "Let's build a docs site"

Config & .env

Config precedence (highest to lowest):

  1. Environment variables already present in your shell or process
  2. .env in the current working directory (loaded only for variables not already set)
  3. ./config.json in the current working directory — provider, model, and optional maxHistoryMessages, maxToolSteps, maxOutputTokens; do not put API keys there.

Key variables: POTION_KIT_PROVIDER (required: openai, anthropic, or moonshot), one of OPENAI_API_KEY, ANTHROPIC_API_KEY, or MOONSHOT_API_KEY, and optionally POTION_KIT_MODEL, POTION_KIT_API_KEY, POTION_KIT_BASE_URL, POTION_KIT_MAX_HISTORY_MESSAGES, POTION_KIT_MAX_TOOL_STEPS, POTION_KIT_MAX_OUTPUT_TOKENS. See the README for full details.

Security: Potion Kit never sends .env or API keys to the model. Never commit .env; add it to .gitignore. Never put API keys in ./config.json. Never paste API keys in chat, logs, or issues.

Chat History

Conversation is stored under .potion-kit/ in the directory where you run potion-kit chat: chat-history.json (messages), chat-summary.json (cached summary for long conversations), and chat-events.json (per-turn tool traces). Each request keeps the first user message, may include a condensed summary of the middle conversation when history gets long, and sends the most recent messages (default 10). Set POTION_KIT_MAX_HISTORY_MESSAGES, POTION_KIT_MAX_TOOL_STEPS, or POTION_KIT_MAX_OUTPUT_TOKENS (or maxHistoryMessages, maxToolSteps, maxOutputTokens in ./config.json) to tune behavior. Add .potion-kit/ to .gitignore if you do not want to commit chat state. Use potion-kit clear to reset history, summary cache, and event traces for that project.

Legal

Potion Kit uses UI Potion specifications and catalog. By using Potion Kit you are using UI Potion's service and agree to the UI Potion legal disclaimer and privacy policy. That page covers disclaimers on AI-generated code, liability, and user responsibility. Please read it before use.

You choose the model and provider (e.g. OpenAI, Anthropic, Kimi). By using a provider you agree to that provider's terms of service and data policies. Potion Kit does not control how providers retain or process your prompts and responses. If your prompts include sensitive data, consider what you send and which provider you use.

Links

Get Started

Browse UI Potion Install Potion Kit (npm)