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:

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.

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.

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:

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