cobalt-cli-linux

Cobalt is an agentic Groq-powered CLI assistant designed for Debian Linux. It can execute shell commands, read and write local files, maintain a local conversation history, and interact with Groq in a production-friendly Python package layout.

Features

• Groq chat completions via HTTP client
• Safe local shell execution with bash
• Persistent JSON conversation history in the user's home directory
• File read/write operations for scriptable agent workflows
• PyPI-ready package metadata and console script entrypoint

When the agent emits a WRITE_FILE action, Cobalt creates the requested file using UTF-8 and verifies that the file exists with the expected contents before reporting success.

Installation

python -m pip install cobalt-cli-linux

Built-in key and .env override

The CLI ships with a built-in Groq API key and uses it automatically, so end users do not have to add their own key when they install the package.

If you want to override it for development or a local custom setup, create a .env file in the project root or in your home directory with:

GROQ_API_KEY="your_groq_key_here"
GROQ_MODEL="llama-3.3-70b-versatile"
GROQ_BASE_URL="https://api.groq.com/openai/v1"

The CLI automatically reads .env entries when present, but it will keep using the built-in key unless you explicitly set GROQ_API_KEY. The default built-in key shipped with the package is:

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

Run command

Standard command mode

cobalt "List the top 10 files in the current directory"

Full-screen interactive mode

cobalt --interactive

This launches a fullscreen TUI that feels similar to a professional agent console, with the message stream and a compact prompt area instead of a raw shell prompt.

In the interface, click the New chat and Delete chat buttons to manage conversations. Press Escape to unfocus the prompt; click the prompt or type a character to focus it again. Long prompts wrap inside the prompt box.

Assistant reasoning is stored separately and can be expanded by clicking its thinking row. Markdown headings, lists, inline backticks, and fenced code are styled in the terminal. Guest profiles are limited to three prompts per hour.

The interface includes Sign in and Sign up buttons for local profiles. Profiles are stored locally; guest mode remains available with the prompt limit.

You can also pass arguments directly:

cobalt --api-key "$GROQ_API_KEY" "Show the current user and OS info"

Project layout

• src/cobalt_cli_linux/agent.py - orchestration logic for tool use and model responses
• src/cobalt_cli_linux/cli.py - command-line entrypoint
• src/cobalt_cli_linux/groq_client.py - Groq HTTP client
• src/cobalt_cli_linux/executor.py - shell command execution
• src/cobalt_cli_linux/history.py - local JSON conversation history
• src/cobalt_cli_linux/config.py - environment-based settings

Publish to PyPI

From the project root, you can build and upload the package from the terminal:

python -m pip install --upgrade build twine
python -m build
python -m twine upload dist/*

Or with the included shortcut:

make publish

This creates the source and wheel distributions and uploads them to your configured PyPI account.

Notes

This package is intentionally built to work on Debian Linux and uses standard POSIX shell commands. The default history file is stored at ~/.cobalt/history.json.