npm package: @stackpulseai/cli
Description: StackPulse AI Command Line Interface
Author: Seu Nome
Latest version: 1.2.0

# StackPulse AI CLI

This is the official reference implementation of a command-line interface (CLI) for interacting with **StackPulse AI**, a productivity platform for development teams.  
The CLI allows you to authenticate, list and manage agents, upload knowledge sources, execute quick commands, and initiate interactive chat sessions with AI.

---

## Features

- **Dual Authentication:**  
  Store both your API token (Base44, hexadecimal) and your application token (user, starts with `sp_`) for full access and security.
- **Agent Management:**  
  List and create agents with custom prompts and settings.
- **Knowledge Source Management:**  
  List or upload new documentation/code files, associate sources by tags or IDs.
- **Quick Command Execution:**  
  Run actions like refactoring, test generation, or code explanation, passing files/snippets and relevant knowledge sources.
- **Interactive Chat:**  
  Start a conversation loop with the AI for technical support, brainstorming, or automation.

---

## Requirements

- Node.js 18+ (latest LTS recommended)
- TypeScript
- Dependencies: `commander`, `inquirer`, `axios`, `chalk`, `ora`, `fs-extra`, etc.  
  See `package.json` for the complete list.

---

## Installation

Install globally via npm:

```bash
npm install -g @stackpulseai/cli
```

This makes the `sp` command available anywhere in your terminal.

---

## Authentication

Before using any commands, you must authenticate with **both** tokens.

### 1. API Token (Base44, hexadecimal)

Use for listing and visualizing agents, sources, and admin commands.

```bash
sp auth-api
```
- Obtain your token from the Base44 dashboard (e.g. `31152bf39af34311a3b1bce13595c4cc`).

### 2. Application Token (user, starts with `sp_`)

Use for commands like chat, execute, create agent/source, etc.

```bash
sp auth-token
```
- Generate your token from the "Tokens API" page inside your StackPulse AI application (e.g. `sp_xxxxxxxx...`).

---

## Usage

Some usage examples after installation:

```bash
# Authenticate your API token (admin access)
sp auth-api

# Authenticate your application token (user access)
sp auth-token

# List available agents
sp agents --list

# Create a new agent (interactive)
sp agents --create

# List knowledge sources
sp sources --list

# Upload a new source
sp sources --add ./docs/api-spec.yaml

# Execute a quick command (ex: refactor code) using a file and tags
sp execute refatorar --file ./src/app.js --tags design-pattern,security

# Start an interactive AI chat session
sp chat

# Show current authentication and config
sp whoami

# Visualize or reset configuration
sp config
```

---

## Project Structure

The CLI is divided into modular components:

- `src/index.ts` – Entry point defining subcommands with Commander.
- `src/commands/` – Folder with implementations for each subcommand (`auth-api`, `auth-token`, `agents`, `sources`, `execute`, `chat`, `whoami`, `config`).
- `src/utils/` – Utilities for configuration (`config.ts`), API communication (`api.ts`).
- `src/types/` – TypeScript interfaces for entities returned by the API.

This structure facilitates maintenance, expansion, and testing.

---

## Contributing

Feel free to open issues and pull requests to fix problems or suggest improvements.  
This CLI is a base you can adapt to your team’s needs.

---

## FAQ

### How do I get the tokens?

- The API token (hexadecimal) is found on the Base44 dashboard.
- The application token (starts with `sp_`) is generated from the "Tokens API" page inside your StackPulse AI app.

### What if my token expires?

- Run `sp auth-api` or `sp auth-token` again to update your token.

### Where are my settings stored?

- Windows: `C:\Users\YourUser\.stackpulse-cli\config.json`
- Linux/macOS: `~/.config/stackpulse-cli/config.json`

### Which token is needed for each command?

- **Listing/visualization:** API token (Base44)
- **Execution, chat, creation:** Application token (user)

---

> Made with ❤️ by the StackPulse AI Team.