🧠 GPT CLI Tool with Persistent Memory and Streaming

A terminal-based GPT assistant powered by the OpenAI API, featuring:

• 🔁 Persistent memory across sessions with summarization
• 🌊 Streaming output (optional)
• 🧾 Command history and logging
• 🧠 Customizable prompt and model
• 🔐 Secure .env configuration

📦 Features

• Conversational memory with summarization after 20 messages
• Markdown-formatted input/output in terminal
• Command history with autocompletion
• Optional streaming mode (prints as it's generated)
• Command-line and one-shot mode
• Log file support for auditing

🚀 Installation

Install the GPT CLI via pip or pipx. Requires Python 3.8+.

Using PyPI

pip install konijima-gpt-cli

Using pipx (recommended)

pipx install konijima-gpt-cli

From GitHub (install directly from source)

# Install directly from the GitHub repo to avoid PyPI conflicts
pip install git+https://github.com/Konijima/gpt-cli.git#egg=konijima-gpt-cli
# or with pipx
pipx install git+https://github.com/Konijima/gpt-cli.git#egg=konijima-gpt-cli

Development Installation

git clone https://github.com/Konijima/gpt-cli.git
cd gpt-cli
pip install .

Update

pip install --upgrade konijima-gpt-cli
# or
pipx upgrade konijima-gpt-cli

Uninstallation

pip uninstall konijima-gpt-cli
# or
pipx uninstall konijima-gpt-cli

🛠️ Environment Setup

A .env file is required to store your API key and configuration.

touch ~/.gpt-cli/.env

Sample .env File

OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-4o
OPENAI_DEFAULT_PROMPT=You are a helpful CLI assistant.
OPENAI_LOGFILE=~/.gpt.log
OPENAI_TEMPERATURE=0.5
OPENAI_MAX_TOKENS=4096
OPENAI_MAX_SUMMARY_TOKENS=2048
OPENAI_MEMORY_PATH=~/.gpt_memory.json
OPENAI_STREAM_ENABLED=false

🔧 Usage

After installation, you can use the gpt command globally.

Interactive Mode

gpt

You’ll enter a REPL-like interface:

🧠 GPT CLI is ready. Type your question or 'exit' to quit.

One-Shot Mode

gpt "Translate 'hello' to French"

From Pipe Input

echo "Write a haiku about the ocean" | gpt

Reset Memory

gpt --reset

This clears all saved memory and summaries, then exits.

Edit Environment Configuration

gpt --env

Opens your .env file in your default terminal editor (e.g., nano, vim, or set via $EDITOR).

Uninstall

gpt --uninstall

This command will completely remove the GPT CLI, including the .env file and virtual environment under ~/.gpt-cli, as well as the global gpt command from ~/.local/bin.

🔐 Environment Variables (Full Reference)

📝 Log Format

If OPENAI_LOGFILE is set, all prompts and responses are saved:

[2025-04-15 15:51:51] Prompt:
Hello there

Response:
Hello there again! What would you like to explore or discuss today?
--------------------------------------------------------------------------------

🧹 Memory

Memory consists of:

• A rolling summary of conversation
• The 10 most recent messages

When 20 messages accumulate, the tool summarizes them into the context summary.

To reset memory:

gpt --reset

❓ Troubleshooting

• ❌ Missing API key: Ensure OPENAI_API_KEY is set in .env
• ❌ Client failed to initialize: Check internet and API credentials
• 💭 Too many tokens: Try a smaller input or enable summarization

🧪 Example Output

You:
Write a joke about servers

GPT:
Why did the server go to therapy?

Because it had too many unresolved requests.

📄 License

MIT License

✨ Credits

Built with ❤️ by Konijima and OpenAI’s GPT models.