A simple AI agent CLI tool for interactive conversations with AI
npm install @profullstack/aiA powerful AI agent CLI tool for interactive conversations with AI, featuring file operations and command execution capabilities.
``bash`
npm install -g @profullstack/ai
Or using pnpm:
`bash`
pnpm add -g @profullstack/ai
- š¤ Interactive AI Chat: Conversational interface with AI models
- š File Operations: Read, write, and delete files with permission prompts
- ā” Command Execution: Run system commands safely with user approval
- š Permission System: Granular control with "allow", "disallow", "allow forever" options
- š Multi-Provider Support: Works with OpenAI GPT and Anthropic Claude models
- āļø Flexible Configuration: Customizable settings and API key management
- š Conversation History: Track and export chat sessions
The AI agent runs in enhanced mode by default, which enables file operations and command execution:
`bash`
ai
This starts an interactive session where the AI can:
- Read and analyze files in your project
- Create, modify, and delete files (with your permission)
- Execute commands like npm install, git status, etc.
- List directory contents and check file existence
Security: You'll be prompted before any file or command operation with options:
- Allow (this time only)
- Disallow (reject the action)
- Allow forever (permanently allow this type of action)
To use the traditional text-only mode without file/command capabilities:
`bash`
ai --no-enhanced
Simply run ai to start an interactive chat session:
`bash`
ai
This will start an interactive prompt where you can have conversations with the AI:
`
š¤ AI Agent
Type your questions or commands. Type "exit" or "quit" to leave.
ai > Hello, how are you?
š¤ Hello! I'm your AI assistant. How can I help you today?
ai > What can you do?
š¤ I can help you with a wide variety of tasks including:
⢠Answering questions on various topics
⢠Helping with writing and editing
⢠Explaining concepts and ideas
⢠Providing suggestions and recommendations
⢠Assisting with problem-solving
⢠And much more! Just ask me anything you'd like help with.
ai > exit
Goodbye! š
`
Ask a single question and get a response:
`bash`
ai ask "What is the capital of France?"
- help or ? - Show help messageclear
- - Clear conversation historyconfig
- - Show current configurationexit
- , quit, or q - Exit the AI agent
Control what actions the AI can perform:
`bashShow current permissions
ai config --show-permissions
Permission Types:
-
file_read - Reading files
- file_write - Writing/creating files
- file_delete - Deleting files
- command_exec - Executing system commandsPermission Levels:
- Allow (this time only) - Permit the action once
- Disallow - Reject the action
- Allow forever - Permanently allow this action type
- [x] Auto-approve - Automatically allow approved actions (for commands in approved list)
$3
Control which commands can be auto-approved:
`bash
Show approved commands list
ai config --show-commandsAdd a command to approved list
ai config --add-command "git status"Remove a command from approved list
ai config --remove-command "rm -rf"Reset to default approved commands
ai config --reset-commands
`Default Approved Commands:
Safe, read-only commands like
ls, pwd, git status, npm list, etc. are pre-approved for auto-execution when auto-approve mode is enabled.Quick Setup
For first-time setup, use the interactive setup command:
`bash
ai setup
`This will guide you through:
- Setting up OpenAI and/or Anthropic API keys
- Choosing your preferred AI model
- Configuring response settings
Configuration
$3
`bash
ai config --show
`$3
`bash
ai config --set model=gpt-4
ai config --set temperature=0.8
ai config --set maxTokens=2000
`$3
`bash
Interactive setup (recommended)
ai setupManual API key setup
ai config --set-openai-key sk-your-openai-key-here
ai config --set-anthropic-key sk-ant-your-anthropic-key-hereCheck API key status
ai config --show-keys
`API keys are stored securely in
~/.config/ai/config.json and can also be set via environment variables:`bash
export OPENAI_API_KEY=sk-your-openai-key-here
export ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
`$3
`bash
ai config --reset
`$3
`bash
Export configuration to a file
ai config --export my-config.jsonImport configuration from a file
ai config --import my-config.json
`$3
Export all your AI agent data (configuration, API keys, conversation history) to a zip file:
`bash
ai export
`This creates
~/ai-agent.zip containing:
- Configuration settings (model, temperature, etc.)
- API keys (OpenAI, Anthropic)
- All conversation historyTo restore on another machine:
`bash
Copy the zip file to the target machine, then:
unzip ~/ai-agent.zip -d ~
`Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
model | string | gpt-3.5-turbo | AI model to use |
| temperature | number | 0.7 | Response creativity (0.0-2.0) |
| maxTokens | number | 1000 | Maximum response length |
| systemPrompt | string | You are a helpful AI assistant. | System prompt |
| verbose | boolean | false | Enable verbose output |
| openaiApiKey | string | null | OpenAI API key for GPT models |
| anthropicApiKey | string | null | Anthropic API key for Claude models |
| apiEndpoint | string | null | Custom API endpoint |Command Line Options
$3
`bash
ai chat [options]
`Options:
-
-m, --model - AI model to use
- -t, --temperature - Response creativity (0.0-2.0)
- --max-tokens - Maximum response length
- --system - System prompt to use
- --verbose - Enable verbose output$3
`bash
ai ask [options]
`Same options as interactive mode.
Examples
$3
`javascript
import { EnhancedAIAgent } from '@profullstack/ai';const agent = new EnhancedAIAgent({
model: 'gpt-3.5-turbo',
temperature: 0.7
});
// AI can now read files, write files, and execute commands
const response = await agent.query('Read my package.json and create a simple README for this project');
console.log(response);
`$3
`javascript
import { AIAgent } from '@profullstack/ai';const agent = new AIAgent({
model: 'gpt-3.5-turbo',
temperature: 0.7
});
const response = await agent.query('Hello, world!');
console.log(response);
`$3
`javascript
import { readFile, writeFile, executeCommand } from '@profullstack/ai';// These functions include built-in permission prompts
const content = await readFile('./myfile.txt');
await writeFile('./output.txt', 'Hello, world!');
const result = await executeCommand('npm test');
`$3
`javascript
import { getConfig, updateConfig, setOpenAIKey, getOpenAIKey } from '@profullstack/ai';// Get current configuration
const config = getConfig();
console.log(config);
// Update configuration
updateConfig('temperature', 0.8);
updateConfig('model', 'gpt-4');
// Set API keys
setOpenAIKey('sk-your-openai-key-here');
setAnthropicKey('sk-ant-your-anthropic-key-here');
// Get API keys
const openaiKey = getOpenAIKey(); // Checks env var first, then config file
const anthropicKey = getAnthropicKey();
`$3
`javascript
import { AIAgent } from '@profullstack/ai';const agent = new AIAgent();
await agent.query('Hello!');
await agent.query('How are you?');
// Get conversation stats
const stats = agent.getStats();
console.log(stats);
// Export history
const history = agent.exportHistory('markdown');
console.log(history);
// Clear history
agent.clearHistory();
`Development
$3
`bash
git clone https://github.com/profullstack/ai.git
cd ai
pnpm install
`$3
`bash
pnpm run example
`$3
`bash
pnpm run cli
`API Reference
$3
The enhanced agent extends AIAgent with file and command capabilities.
#### Constructor
`javascript
new EnhancedAIAgent(options)
`Options:
-
model - AI model to use
- temperature - Response creativity
- maxTokens - Maximum response length
- system - System prompt
- verbose - Enable verbose output
- enableActions - Enable file/command operations (default: true)#### Methods
-
query(message) - Send a message and get a response (with action processing)
- clearHistory() - Clear conversation history
- getHistory() - Get conversation history
- getStats() - Get conversation statistics
- exportHistory(format) - Export history in specified format
- setActionsEnabled(enabled) - Enable/disable action processing
- getActionsEnabled() - Check if actions are enabled$3
Basic text-only agent without file/command capabilities.
#### Constructor
`javascript
new AIAgent(options)
`Options:
-
model - AI model to use
- temperature - Response creativity
- maxTokens - Maximum response length
- system - System prompt
- verbose - Enable verbose output#### Methods
-
query(message) - Send a message and get a response
- clearHistory() - Clear conversation history
- getHistory() - Get conversation history
- getStats() - Get conversation statistics
- exportHistory(format) - Export history in specified format$3
-
getConfig() - Get current configuration
- updateConfig(key, value) - Update configuration value
- resetConfig() - Reset to default configuration
- exportConfig(filePath) - Export configuration to file
- importConfig(filePath) - Import configuration from file
- validateConfig(config) - Validate configuration
- getAvailableModels() - Get list of available models
- getConfigSchema() - Get configuration schema
$3
File and command operations with built-in permission prompts:
-
readFile(filePath) - Read a file with permission check
- writeFile(filePath, content) - Write to a file with permission check
- deleteFile(filePath) - Delete a file with permission check
- executeCommand(command, options) - Execute a command with permission check
- listFiles(dirPath) - List files in a directory
- fileExists(filePath) - Check if a file exists$3
-
resetPermissions() - Reset all action permissions
- showPermissions() - Display current permission settings
- ACTION_TYPES - Constants for action types
- PERMISSION_LEVELS - Constants for permission levels$3
-
getOpenAIKey() - Get OpenAI API key (env var or config file)
- setOpenAIKey(key) - Set OpenAI API key in config file
- getAnthropicKey() - Get Anthropic API key (env var or config file)
- setAnthropicKey(key)` - Set Anthropic API key in config fileMIT
Contributions are welcome! Please feel free to submit a Pull Request.
For support, please open an issue on GitHub or contact us at support@profullstack.com.