cbot-cli 0.3.0
A local-first CLI helper for productivity and automation.
License: MIT
Requires Python: >=3.7
Keywords: cli, productivity, automation, local-first

## Cbot-cli Basics

Local first, cli chat and agentic application that calls the Llama3.2 (Ollama) text completion endpoint by default with a system message and can identify the OS of the current system. This helps ensure that Linux, Mac, and Windows specific commands tend to be more accurate.

## Installation

## From PyPI (Recommended):
```bash
pip install cbot-cli
```

Or using uv:
```bash
uv add cbot-cli
```

For isolated environments, consider using a virtual environment:
```bash
python -m venv cbot_env
source cbot_env/bin/activate  # On Windows: cbot_env\Scripts\activate
pip install cbot-cli
```

Or using uv to create and manage a virtual environment:
```bash
uv venv cbot_env
source cbot_env/bin/activate  # On Windows: cbot_env\Scripts\activate
uv pip install cbot-cli
```

## From Source
Cbot-cli uses modern Python packaging with pyproject.toml for dependency management:

Installing with -e puts the package in development mode, allowing you to modify the code without reinstalling.

## For Development: 
- Clone this repo to your computer using your terminal.
- `cd ~/<your-directory>/cbot-cli/`
- Run `pip install -e .` inside your cbot directory

- A "cbot-cli" command should be available to use cbot from your CLI, e.g. `cbot-cli -g "Who was the 45th president of the United States?`

- cbot will automatically store questions, responses and agent memory in a local SQLite database located at `~/.cbot_cache`

- NOTE: For the script to work, you will need to have Ollama running in the background. To install a desired Ollama model go to https://ollama.com/search

## Setup Requirements

### For Ollama Models (Default - Recommended for Local Use)

1. **Install Ollama**: Visit [ollama.com](https://ollama.com) and follow the installation instructions for your OS
2. **Start Ollama**: Ensure Ollama is running in the background
3. **Pull Required Models**: Run these commands to download the models cbot-cli supports:

```bash
# Default model (llama3.2)
ollama pull llama3.2
```

### For OpenAI API (Cloud-based)

If you prefer to use OpenAI's models instead of local Ollama models:

1. **Get an OpenAI API Key**: Sign up at [platform.openai.com](https://platform.openai.com) and create an API key
2. **Set Environment Variable**: Add your API key to your environment:

```bash
# Add to your ~/.zshrc, ~/.bashrc, or ~/.bash_profile
export OPENAI_API_KEY="your-api-key-here"

# Or create a .env file in your project directory
echo "OPENAI_API_KEY=your-api-key-here" > ~/.env
```

#### How to set your OpenAI API key (for non-developers)

**macOS & Linux:**
1. Open your Terminal app.
2. Run this command (replace with your actual key):
   ```bash
   export OPENAI_API_KEY="your-api-key-here"
   ```
3. To make it permanent, add the above line to your shell config file:
   - For zsh: `echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc`
   - For bash: `echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc`
4. Reload your shell:
   ```bash
   source ~/.zshrc  # or source ~/.bashrc
   ```

**Windows:**
1. Open Command Prompt.
2. Run:
   ```cmd
   setx OPENAI_API_KEY "your-api-key-here"
   ```
3. Close and reopen Command Prompt for changes to take effect.
4. Alternatively, you can set environment variables via System Properties > Environment Variables.

**.env file (all platforms):**
You can also create a file named `.env` in your project folder and add this line:
```
OPENAI_API_KEY=your-api-key-here
```
Some tools will automatically read this file.

3. **Reload your shell** or run:
```bash
source ~/.zshrc  # or ~/.bashrc
```

**Note**: OpenAI API usage incurs costs based on your usage. Check OpenAI's pricing at [openai.com/pricing](https://openai.com/pricing)


## Model Selection
  
You can choose which Ollama model Cbot uses by passing one of these flags before your question:
  
- `-l32` : use `llama3.2` (default)  

To use OpenAI models: 
- `-oa`: use `openai o4-mini`
  
Example:
  
```
cbot-cli -l32 -g "List files in my home directory"
cbot-cli -oa -g "Who is the president of the United States?"
```

You can also call cbot with a **-s** option. This will save any command as a shortcut with whatever name you choose. The first parameter is the name of the command and the second is the command itself in quotes.

```
$> cbot-cli -s nap "pmset sleepnow"
   Saving shortcut nap, will return: pmset sleepnow
$> cbot-cli -x nap
   Sleeping now...
```

To copy a command directly into the clipboard use the **-c** option. Can be useful if you want to execute the command but you don't trust cbot to do so automatically.

Cbot has a -g option to ask general questions. The results when you ask a general question will not be formated as a command line. This is useful for asking general questions, historical facts or other information not likely to be formated as a command.

```
$> cbot-cli -g "Who was the 23rd president?"
  Herbert Hoover
$> cbot-cli -g "What is the meaning of life?"
   42
```

## Agent Mode

Cbot includes an agent mode with persistent conversation memory using the **-a** flag. In agent mode, the AI maintains context across multiple interactions, remembering your conversation history even between sessions.

```
$> cbot-cli -a
   Entering agent mode. Type 'exit' to end the agent chat.
   Type 'clear' to clear conversation history.
You: What's my name?
Agent: I don't have any information about your name from our conversation.

You: My name is John
Agent: Nice to meet you, John! I'll remember that.

You: exit
   Exiting chat mode.
```

When you restart agent mode later, it will remember previous conversations. Use `clear` to reset the conversation history if needed.

---

This code is free to use under the MIT license.