HeroPrompt
Back to docs
Getting Started

Installation Guide

Install the HeroPrompt CLI and configure your environment.

Updated 2026-02-15

Installation Guide

Install the HeroPrompt CLI to sync prompts to your local machine and access them offline.

Prerequisites

  • Python 3.8+ (Python 3.11+ recommended)
  • pip or pipx for package installation

Check your Python version:

bash
python --version
# or
python3 --version

Installation Methods

Option 1: Using pip (Recommended)

bash
pip install heroprompt-cli

This installs the CLI globally on your system.

Option 2: Using pipx (Isolated Installation)

pipx installs CLI tools in isolated environments:

bash
# Install pipx if you don't have it
pip install pipx
pipx ensurepath

# Install heroprompt-cli
pipx install heroprompt-cli

Recommended for developers — avoids dependency conflicts with other Python packages.

Option 3: From Source

bash
git clone https://github.com/heroprompt/heroprompt-cli.git
cd heroprompt-cli
pip install -e .

Verify Installation

bash
heroprompt version
# heroprompt-cli version 0.1.0

If the command is not found, ensure your Python scripts directory is in your PATH:

  • Linux/macOS: ~/.local/bin or /usr/local/bin
  • Windows: %APPDATA%\Python\Scripts

First Time Setup

1. Generate a Personal Access Token

Visit Settings and create a new token under "Personal Access Tokens".

Token limits by tier:

  • Free: 0 tokens (CLI not available)
  • Starter: 1 token
  • Pro Kit: 3 tokens
  • Lifetime: 5 tokens

2. Login

bash
heroprompt login --token hp_pat_your_token_here

This saves your authentication info to ~/.heroprompt/config.json.

3. Verify Authentication

bash
heroprompt status

You should see your account information and tier.

Configuration

The CLI stores all data in ~/.heroprompt/:

text
~/.heroprompt/
├── config.json       # Auth token and settings
├── prompts/          # Synced prompts
└── skills/           # Synced Skills (PRO+ only)

For custom API URLs (self-hosted or local development):

bash
heroprompt login --token hp_pat_xxxxx --api-url http://localhost:8000/api

Upgrading

bash
# pip
pip install --upgrade heroprompt-cli

# pipx
pipx upgrade heroprompt-cli

Uninstalling

bash
# pip
pip uninstall heroprompt-cli

# pipx
pipx uninstall heroprompt-cli

# Remove configuration
rm -rf ~/.heroprompt

Troubleshooting

Command not found

Ensure Python's scripts directory is in your PATH:

bash
# macOS/Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or check where pip installed the CLI
pip show heroprompt-cli

Authentication errors

  • Verify your token is active (check Settings)
  • Ensure you have at least a Starter subscription
  • Try logging out and back in: heroprompt logout && heroprompt login

Permission errors

On Unix systems, the config file is created with 0600 permissions (user-only readable). If you get permission errors:

bash
chmod 600 ~/.heroprompt/config.json
Previous
Quick Start
Next
Using Prompts