Soul CLI

Give your ideas a soul: AI code agent

Soul CLI is an enhanced AI agent built on Google's Gemini CLI foundation. It brings the power of Gemini directly into your terminal with additional features and customizations for advanced development workflows.

Quick Start

Install

npm install -g @nightskyai/soul-cli-ai

Run

soul

System Requirements

• Node.js version 20 or higher
• macOS, Linux, or Windows (via WSL)

Key Features

• Free tier: 60 requests/min and 1,000 requests/day with personal Google account
• Powerful Gemini 2.5 Pro: Access to 1M token context window
• Enhanced tools: Advanced file operations, shell commands, web fetching, and custom agent system
• Extensible: MCP (Model Context Protocol) support for custom integrations
• Terminal-first: Designed for developers who live in the command line
• Task Management: Built-in todo tracking for complex workflows
• Open source: Apache 2.0 licensed

Installation Guides

• macOS/Linux Installation
• Windows Installation Guide - Step-by-step WSL setup
• Authentication Setup - OAuth, API keys, and Vertex AI

Examples & Use Cases

Check out EXAMPLES.md for comprehensive examples:

• 3D Game Development (Unity, Three.js, Godot)
• Full-Stack Web Application Planning
• Multimodal Applications (Image/Video processing)
• DevOps & CI/CD Automation
• Data Analysis & ML Deployment

Documentation

Getting Started

• Quickstart Guide
• Configuration
• Commands Reference
• Keyboard Shortcuts

Features

• Built-in Tools
• MCP Server Integration
• Memory Management
• Checkpointing

Advanced

• Architecture Overview
• Custom Extensions
• IDE Integration
• Enterprise Deployment

Support

• Troubleshooting
• FAQ
• Uninstall Guide

Authentication Options

Option 1: OAuth login (Recommended)

soul
# Choose OAuth and follow browser authentication

• Free tier: 60 requests/min, 1,000 requests/day
• No API key management required

Option 2: Gemini API Key

export GEMINI_API_KEY="YOUR_API_KEY"
soul

• Get your key from Google AI Studio

Option 3: Vertex AI (Enterprise)

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
soul

See all authentication options →

Quick Examples

Create a new project

soul
> Write me a Discord bot that answers questions using a FAQ.md file

Analyze existing code

soul
> Give me a summary of all changes in the last 24 hours

Use with specific model

soul -m gemini-2.5-flash

Non-interactive mode

soul -p "Explain the architecture of this codebase"

GitHub Integration

Integrate Soul CLI into your workflows:

• Pull Request Reviews: Automated code review with feedback
• Issue Triage: Automated labeling and prioritization
• CI/CD Pipelines: Use in automated workflows

MCP Servers

Extend Soul CLI with custom tools via ~/.gemini/settings.json:

> @github List my open pull requests
> @slack Send today's commits summary to #dev
> @database Find inactive users

Learn more about MCP →

What's New in Soul CLI

Soul CLI extends Gemini CLI with:

• Enhanced Tool System with specialized agents
• Built-in task management
• Flexible system prompt configuration
• Comprehensive examples and guides
• Optimized build system

Legal

• License: Apache License 2.0
• Terms: Terms & Privacy
• Security: Security Policy

---

Built by Nightsky Labs.ai, based on Google's Gemini CLI
Special thanks to the Google Gemini team and the open source community