ghost-forge-cli

Official command-line client for GhostGPT API at https://api.ghostgpt.live.

ghost-forge-cli is an operator-friendly wrapper around your OpenAI-compatible endpoints:

• POST /v1/chat/completions
• GET /v1/models

It is built for your project flow (API key auth with ghost_... keys) and supports:

• one-shot prompt generation,
• interactive chat,
• model discovery,
• local session history.

---

1) Requirements

• Linux/macOS with Python 3.10+
• API key from your GhostGPT dashboard (ghost_...)

---

2) Install from source

From the project root:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install .

This installs the command:

ghost-forge --help

---

3) Configure for api.ghostgpt.live

Defaults are auto-created on first run:

• api_base_url: https://api.ghostgpt.live
• timeout: 120

If no API key is found, the CLI will prompt once and save it.

Option A (recommended): saved local config

ghost-forge config set -u https://api.ghostgpt.live -k ghost_your_real_key -t 120

Check config:

ghost-forge config show

Option B: environment variables

export GHOSTGPT_API_BASE_URL="https://api.ghostgpt.live"
export GHOSTGPT_API_KEY="ghost_your_real_key"

---

4) Core commands

ghost-forge models

List models available to your key and plan.

ghost-forge models

Example output:

Available models
- ghost-nano
- ghost-pro

ghost-forge generate "<prompt>"

One-shot non-stream completion.

ghost-forge generate "Write a secure nginx config for SSE proxying"

With options:

ghost-forge generate \
  "Draft a Python retry wrapper for requests" \
  -m ghost-pro \
  -n 1400 \
  -T 0.2 \
  -o ./output.txt

ghost-forge chat

Interactive REPL-style prompt loop.

ghost-forge chat -m ghost-nano -n 1024

Exit with exit or quit.

---

5) History commands

The CLI stores local history at:

• ~/.local/share/ghost-forge/session.json

Show history:

ghost-forge history show --limit 20

Clear history:

ghost-forge history clear

---

6) API contract this CLI expects

The CLI posts to:

• https://api.ghostgpt.live/v1/chat/completions

Request shape:

{
  "model": "ghost-nano",
  "messages": [{"role": "user", "content": "Hello"}],
  "stream": false,
  "max_tokens": 1024,
  "temperature": 0.2
}

Headers:

Authorization: Bearer ghost_xxx
Content-Type: application/json

Model listing call:

• GET https://api.ghostgpt.live/v1/models

---

7) Example operator workflow

# 1) Configure key once
ghost-forge config set -k ghost_xxx -u https://api.ghostgpt.live

# 2) Check model entitlements
ghost-forge models

# 3) Generate a one-shot answer
ghost-forge generate "Create a FastAPI endpoint with pydantic validation" -m ghost-nano

# 4) Start an interactive session
ghost-forge chat -m ghost-pro

---

8) Troubleshooting

Missing API key

Set one via:

ghost-forge config set --api-key ghost_xxx

401 Unauthorized

• Verify key prefix is ghost_
• Ensure key is active in your backend/dashboard

403 Model requires plan

Your key plan cannot access requested model. Use ghost-forge models to see available IDs.

429 Daily limit reached

Free-tier or throttle policy hit in your API backend.

Request timed out

Longer generations can exceed the client timeout. Increase it globally or per command:

ghost-forge config set -t 180
# or one-off
ghost-forge -t 180 generate "Your prompt"

---

9) Quick command reference

ghost-forge --help
ghost-forge config show
ghost-forge config set -k ghost_xxx -u https://api.ghostgpt.live
ghost-forge models
ghost-forge generate "Your prompt"
ghost-forge chat
ghost-forge history show -l 20
ghost-forge history clear