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.

$3

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

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

$3

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

$3

- 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.

$3

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

$3

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

$3

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

---

> Made with ❤️ by the StackPulse AI Team.