Metadata-Version: 2.1
Name: codemie-plugins
Version: 0.1.120
Summary: Command-line interface for running CodeMie Plugins toolkits
Author: CodeMie Team
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: click (==8.1.8)
Requires-Dist: gitpython (>=3.1.44,<4.0.0)
Requires-Dist: langchain (>=0.3.23,<0.4.0)
Requires-Dist: langchain-community (>=0.3.21,<0.4.0)
Requires-Dist: langchain-mcp-adapters (>=0.0.7,<0.0.8)
Requires-Dist: langchain-openai (>=0.3.12,<0.4.0)
Requires-Dist: langgraph (>=0.3.27,<0.4.0)
Requires-Dist: mcp (>=1.6.0,<2.0.0)
Requires-Dist: nats-py (==2.10.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: protobuf (==5.27.3)
Requires-Dist: pydantic (>=2.11.3,<3.0.0)
Requires-Dist: pyfiglet (>=1.0.2,<2.0.0)
Requires-Dist: rich (==14.0.0)
Description-Content-Type: text/markdown

# EPAM AI/Run CodeMie Plugins CLI

A command-line interface for running AI/Run CodeMie Plugins toolkits.

## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
  - [Using pip](#using-pip)
  - [From Source](#from-source)
- [Configuration](#configuration)
  - [Setting Up Your Plugin Key](#setting-up-your-plugin-key)
  - [Configuration File](#configuration-file)
  - [Environment Variables](#environment-variables)
- [Commands](#commands)
  - [Global Options](#global-options)
  - [List Command](#list-command)
  - [Config Command](#config-command)
  - [MCP Command](#mcp-command)
  - [Development Command](#development-command)
- [Code Command](#code-command)
- [Custom MCP Servers](#custom-mcp-servers)
- [Graceful Shutdown](#graceful-shutdown)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Overview

The CodeMie Plugins CLI provides a convenient way to interact with CodeMie toolkits and MCP (Model Context Protocol) servers. It offers a unified interface for:

- Running development toolkits on repositories
- Managing and running MCP servers
- Configuring plugin settings
- Listing available commands and toolkits

This CLI is designed to be cross-platform and easy to use, with a focus on developer experience.

## Installation

### Using uvx (Recommended)

Recommended option to install cli is to use `uvx`(For installation instructions for `uvx`, see the [uv documentation](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv)):

```bash
# Install
uvx pip install codemie-plugins

# Run
uvx codemie-plugins
```

### Using pip

Pip installation:

```bash
pip install codemie-plugins
```

### From Source

To install from source:

```bash
# Clone the repository
git clone https://gitbud.epam.com/epm-cdme/codemie-plugins.git
cd codemie-plugins

# Install using pip
pip install -e .

# Or using poetry
poetry install
```

## Configuration

### Setting Up Your Plugin Key

Before using the CLI, you need to set up your plugin key:

1. Generate a plugin key using the built-in command:
   ```bash
   codemie-plugins config generate-key
   ```
   This will generate a random UUID and set it as your plugin key.

2. Alternatively, set a specific plugin key in your configuration:
   ```bash
   codemie-plugins config set PLUGIN_KEY your-plugin-key
   ```

3. Or set it as an environment variable:
   ```bash
   export PLUGIN_KEY=your-plugin-key
   ```

### Configuration File

The CLI uses a configuration file located at `$HOME/.codemie/config.json`. You can manage this configuration using the `config` command:

```bash
# View current configuration
codemie-plugins config list

# Set a configuration value
codemie-plugins config set KEY VALUE

# Get a specific configuration value
codemie-plugins config get KEY
```

### Environment Variables

The following environment variables can be used to configure the CLI:

- `PLUGIN_KEY`: Authentication key for the plugin engine
- `PLUGIN_ENGINE_URI`: URI for the plugin engine (typically a NATS server)
- `COMMAND_LINE_TOOL_TIMEOUT`: Timeout for command line tools (in seconds)

## Commands

### Global Options

The following options are available for all commands:

```
--plugin-key TEXT          Authentication key for the plugin engine
--plugin-engine-uri TEXT   URI for the plugin engine (typically a NATS server)
--debug / --no-debug       Enable debug mode
--version                  Show the version and exit
--help                     Show help message and exit
```

### List Command

The `list` command displays available CLI commands:

```bash
codemie-plugins list [OPTIONS]
```

Options:
- `--verbose, -v`: Display detailed information about each command

Example:
```bash
# List available commands
codemie-plugins list
# or with uvx
uvx codemie-plugins list

# List commands with detailed information
codemie-plugins list -v
# or with uvx
uvx codemie-plugins list -v
```

### Config Command

The `config` command manages CLI configuration settings:

```bash
codemie-plugins config SUBCOMMAND [OPTIONS]
```

Subcommands:
- `list`: List current configuration settings
  - `--all`: Show all configuration including environment variables
- `set KEY VALUE`: Set a configuration value
- `get KEY`: Get a specific configuration value
- `generate-key`: Generate a random UUID and set it as the plugin key

Examples:
```bash
# List current configuration
codemie-plugins config list
# or with uvx
uvx codemie-plugins config list

# Show all configuration
codemie-plugins config list --all
# or with uvx
uvx codemie-plugins config list --all

# Set a configuration value
codemie-plugins config set PLUGIN_KEY your-plugin-key
# or with uvx
uvx codemie-plugins config set PLUGIN_KEY your-plugin-key

# Get a specific configuration value
codemie-plugins config get PLUGIN_KEY
# or with uvx
uvx codemie-plugins config get PLUGIN_KEY

# Generate a random UUID and set it as the plugin key
codemie-plugins config generate-key
# or with uvx
uvx codemie-plugins config generate-key
```

### MCP Command

The `mcp` command manages Model Context Protocol servers and connections:

```bash
codemie-plugins mcp SUBCOMMAND [OPTIONS]
```

Subcommands:
- `list`: List available MCP servers
- `run`: Run MCP with specified servers
  - `--servers, -s TEXT`: Comma-separated list of server names to run (required)
  - `--env, -e TEXT`: Server-specific environment variables (format: 'server_name=VAR1,VAR2')
  - `--timeout, -t INTEGER`: Timeout in seconds

Examples:
```bash
# List available MCP servers
codemie-plugins mcp list
# or with uvx
uvx codemie-plugins mcp list

# Run a single server
codemie-plugins mcp run -s filesystem
# or with uvx
uvx codemie-plugins mcp run -s filesystem

# Run multiple servers
codemie-plugins mcp run -s filesystem,cli-mcp-server -e cli-mcp-server=ALLOWED_DIR
# or with uvx
uvx codemie-plugins mcp run -s filesystem,cli-mcp-server -e cli-mcp-server=ALLOWED_DIR

# Run with environment variables
codemie-plugins mcp run -s filesystem -e filesystem=FILE_PATHS
# or with uvx
uvx codemie-plugins mcp run -s filesystem -e filesystem=FILE_PATHS
```

### Development Command

The `development` command provides development toolkit commands for working with repositories:

```bash
codemie-plugins development SUBCOMMAND [OPTIONS]
```

Subcommands:
- `run`: Run development toolkit on a repository
  - `--repo-path PATH`: Path to the repository directory
  - `--timeout, -t INTEGER`: Timeout in seconds for command execution

Examples:
```bash
# Run development toolkit on current directory
codemie-plugins development run
# or with uvx
uvx codemie-plugins development run

# Run development toolkit on a specific repository
codemie-plugins development run --repo-path /path/to/repo
# or with uvx
uvx codemie-plugins development run --repo-path /path/to/repo

# Run with a custom timeout
codemie-plugins development run --timeout 600
# or with uvx
uvx codemie-plugins development run --timeout 600
```

### Code Command

The `code` command launches an interactive AI-powered coding assistant that helps with various programming tasks:

```bash
codemie-plugins code [OPTIONS]
```

Options:
- `--model, -m TEXT`: The model to use for the coding assistant (default: gpt-4o)
- `--temperature, -t FLOAT`: Temperature setting for the model (0.0-1.0) (default: 0.7)
- `--allowed-dir, -d TEXT`: Directories the agent is allowed to access (can specify multiple)
- `--verbose, -v`: Verbose mode to avoid logs truncation
- `--recursion-limit, -r INTEGER`: Maximum recursion limit for the agent (default: 50)
- `--global-prompt, -g`: Use the default global prompt even if a local prompt is configured
- `--mcp-servers TEXT`: Comma-separated list of MCP server names to include in the agent

#### Examples:
Start the interactive coding assistant
```bash
# Default run
codemie-plugins code
# or with uvx
uvx codemie-plugins code
```

Use a specific model
```bash
# gpt-4o example
codemie-plugins code --model gpt-4o
# or with uvx
uvx codemie-plugins code --model gpt-4o

# Claude Sonnet 3.7
codemie-plugins code --model anthropic.claude-3-7-sonnet-20250219-v1:0
# or with uvx
uvx codemie-plugins code --model anthropic.claude-3-7-sonnet-20250219-v1:0
```

Set a custom temperature
```bash
# Configure agent temperature
codemie-plugins code --temperature 0.2
# or with uvx
uvx codemie-plugins code --temperature 0.2
```

Specify allowed directories to access on local file system
```bash
# Specify allowed directories (Absolute path should be provided)
codemie-plugins code --allowed-dir /path/to/project
# or with uvx
uvx codemie-plugins code --allowed-dir /path/to/project
```

Use with specific LLM service configuration
```bash
# Pass api key and url
codemie-plugins code --llm-api-key your-api-key --llm-base-url https://your-llm-service.com
# or with uvx
uvx codemie-plugins code --llm-api-key your-api-key --llm-base-url https://your-llm-service.com
```

Overwrite default prompt
```bash
# Use with a local prompt (overrides default)
codemie-plugins config local-prompt "Your custom prompt"
codemie-plugins code
# or with uvx
uvx codemie-plugins config local-prompt "Your custom prompt"
uvx codemie-plugins code
```

Force usage of global prompt
```bash
# Force using the default global prompt
codemie-plugins code -g
# or with uvx
uvx codemie-plugins code -g
```

Use MCP servers (should be configured in advance). See [Custom MCP Servers](#custom-mcp-servers) section
```bash
# Use with MCP servers
codemie-plugins code --mcp-servers jetbrains
# or with uvx
uvx codemie-plugins code --mcp-servers jetbrains
```

#### Interactive Mode Commands

Once in the interactive mode, you can use the following commands:
- `exit`: Exit the interactive mode
- `reset`: Reset the conversation history

#### Custom Prompts

You can customize the agent's behavior by providing a custom prompt:

1. Create a file at `$HOME/.codemie/prompt.txt` with your custom instructions
2. Run the code command, and it will automatically use your custom prompt
3. To force using the default prompt, use the `--global-prompt` flag

#### For Development
For local development it's recommended to use default agent with sonnet-3.5 or 3.7 models and point to specific 
directory to work with.
As an example you are developing in `$HOME/repos/EPMCDME/codemie` and `$HOME/repos/EPMCDME/codemie-ui` directories.
Run the following commands to start `codemie-plugins code` with claude 3.7 model

```bash
codemie-plugins code --allowed-dir $HOME/repos/EPMCDME/codemie --allowed-dir $HOME/repos/EPMCDME/codemie-ui --model anthropic.claude-3-7-sonnet-20250219-v1:0
# or with uvx
uvx codemie-plugins code --allowed-dir $HOME/repos/EPMCDME/codemie --allowed-dir $HOME/repos/EPMCDME/codemie-ui --model anthropic.claude-3-7-sonnet-20250219-v1:0
```

## Custom MCP Servers

You can define custom MCP servers in your global configuration file (`$HOME/.codemie/config.json`). These servers will be automatically recognized and can be used alongside the predefined servers.

Configuration Format:

```json
{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "transport": "stdio"
    }
  }
}
```

Using Custom Servers:

```bash
# List all available servers including custom ones
codemie-plugins mcp list
# or with uvx
uvx codemie-plugins mcp list

# Run a custom server
codemie-plugins mcp run -s my-custom-server
# or with uvx
uvx codemie-plugins mcp run -s my-custom-server
```

## Graceful Shutdown

The CLI implements graceful shutdown handling to ensure that all processes are properly terminated when the CLI is interrupted (e.g., with Ctrl+C). This includes:

- Cancelling running asyncio tasks
- Terminating subprocesses
- Closing connections

## Troubleshooting

If you encounter issues with the CLI, try the following:

1. Enable debug mode:
   ```bash
   codemie-plugins --debug COMMAND
   # or with uvx
   uvx codemie-plugins --debug COMMAND
   ```

2. Check your configuration:
   ```bash
   codemie-plugins config list --all
   # or with uvx
   uvx codemie-plugins config list --all
   ```

3. Ensure your plugin key is correctly set:
   ```bash
   codemie-plugins config get PLUGIN_KEY
   # or with uvx
   uvx codemie-plugins config get PLUGIN_KEY
   ```

4. Verify that required environment variables are set for specific servers.

## Contributing

Contributions to the CodeMie Plugins CLI are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

© 2025 EPAM AI/Run CodeMie Team
