Abra Evolve CLI

A lightweight CLI tool to interact with the Abra Evolve AI agent backend.

Installation

Global Installation (Recommended)

npm install -g @abra-evolve/cli

Local Development

cd cli
npm install
npm run build
npm link  # Creates global symlink for testing

Usage

# Check backend status
abra status

# Chat with the agent
abra chat "Hello, how are you?"

# Get help
abra --help
abra chat --help

Configuration

Create a .env file in your home directory or project:

ABRA_API_URL=http://localhost:8000
ABRA_API_KEY=your-api-key  # Optional

Or set environment variables:

export ABRA_API_URL=https://your-backend.com

Adding New Commands

Adding a new command is dead simple - just 3 steps:

Step 1: Create your command file

Create src/commands/yourcommand.ts:

import { Command } from "commander";
import chalk from "chalk";
import { apiClient } from "../api/client";
import { handleError } from "../utils/error-handler";
import type { YourResponse } from "../types";

export const yourCommand = new Command("yourcommand")
  .description("What your command does")
  .argument("<input>", "What the user should provide")
  .option("-f, --flag", "Optional flag")
  .action(async (input: string, options): Promise<void> => {
    try {
      console.log(chalk.blue("🚀 Doing something cool..."));
      const response = await apiClient.post<YourResponse>("/your-endpoint", {
        input,
      });
      console.log(chalk.green("✅ Done!"), response.data);
    } catch (error) {
      handleError(error);
    }
  });

Step 2: Register it

Add one line to src/commands/index.ts:

import { yourCommand } from "./yourcommand";

export function registerCommands(program: Command): void {
  program.addCommand(chatCommand);
  program.addCommand(statusCommand);
  program.addCommand(yourCommand); // ← Add this line
}

Step 3: Rebuild

npm run build
abra yourcommand "test"

That's it! Your new command is now available.

Development

# Watch mode (rebuilds on file changes)
npm run dev

# Build
npm run build

# Test locally
npm link
abra status

Project Structure

cli/
├── bin/
│   └── abra.js              # Executable shim (3 lines)
├── src/                     # 100% TypeScript source
│   ├── cli.ts               # CLI entry point
│   ├── index.ts             # Public exports
│   ├── commands/            # ONE FILE = ONE COMMAND
│   │   ├── index.ts         # ← Register commands here (1 line each)
│   │   ├── chat.ts          # ← Command: abra chat
│   │   ├── status.ts        # ← Command: abra status
│   │   └── help.ts          # ← Command: abra help
│   ├── api/
│   │   └── client.ts        # Axios client with auth & error handling
│   ├── types/
│   │   └── index.ts         # Shared TypeScript types
│   └── utils/
│       └── error-handler.ts # Centralized error handling
├── dist/                    # Compiled output (auto-generated)
├── package.json
├── tsconfig.json
└── README.md

Organization Principle

ONE FILE = ONE COMMAND

Every command lives in its own file in src/commands/:

• chat.ts → abra chat
• status.ts → abra status
• help.ts → abra help
• yourcommand.ts → abra yourcommand

Then register it in src/commands/index.ts with one line:

program.addCommand(yourCommand);

That's it! No magic, everything is explicit.

Publishing

# Update version in package.json
npm version patch  # or minor, major

# Build and publish
npm run build
npm publish --access public