wordlift-cli/README.md

WordLift CLI - Your AI SEO Assistant powered by Google Gemini. Agentic SEO workflows with Agent Skills support, WordLift MCP integration, knowledge graphs, and intelligent content optimization for modern content creators.

# WordLift CLI 🚀

**WordLift CLI - Your AI SEO Assistant** - An intelligent command-line interface powered by Google Gemini, designed specifically for SEO professionals and content creators. Get expert SEO guidance, content optimization, and knowledge graph integration right from your terminal.

> **🆕 Version 1.7.17 Available!** - Includes Gemini CLI 0.38.2 upgrade, Node 20+ alignment, and automated test suite. [Update now](#-staying-updated) for the best experience.

🤖 **[AI SEO Agent](https://wordlift.io/agent/)** | 📚 **[Documentation](https://docs.wordlift.io/agent-wordlift/integrations/#wordlift-cli)** | 💬 **[Get Support](https://github.com/wordlift/wordlift-cli/issues)** | 🧠 **[Learn More about Agentic SEO](https://wordlift.io/blog/en/agentic-ai/)**

## 🎨 WordLift CLI in Action

When you run `npx wordlift-cli`, you'll see the beautiful WordLift ASCII art logo:

```text
██     ██  ██████  ██████  ██████  ██      ██ ███████ ████████
██     ██ ██    ██ ██   ██ ██   ██ ██      ██ ██         ██
██  █  ██ ██    ██ ██████  ██   ██ ██      ██ █████      ██
██ ███ ██ ██    ██ ██   ██ ██   ██ ██      ██ ██         ██
 ███ ███   ██████  ██   ██ ██████  ███████ ██ ██         ██
```

🚀 **WordLift CLI - Your SEO Assistant**

The CLI provides helpful tips to get you started:

1. Ask questions, edit files, or run commands.
2. Be specific for the best results.
3. `/help` for more information.

## ✨ Features

- **🤖 AI-Powered SEO Assistant**: Intelligent content creation and optimization powered by Google Gemini
- **🎯 Agent Skills Support**: Extensible architecture for specialized SEO expertise (experimental)
- **📊 Knowledge Graph Integration**: SEOVoc-based memory system for storing strategies and guidelines
- **🎨 Beautiful CLI Experience**: Custom branding and intuitive command interface
- **⚡ Fast & Easy Setup**: Install globally via npm or run instantly with npx
- **🔧 Full Project Access**: Smart directory detection with complete file system integration
- **👥 Team Ready**: Designed for collaborative SEO and content workflows

## 🤖 WordLift AI SEO Agent

This CLI is part of the **[AI SEO Agent](https://wordlift.io/agent/)** ecosystem - the most advanced AI-powered SEO platform.

**🚀 [Get started with AI SEO Agent →](https://wordlift.io/agent/)**

- **Complete SEO Automation**: From keyword research to content optimization
- **Knowledge Graph Integration**: Semantic SEO powered by structured data
- **AI Content Creation**: Generate SEO-optimized content at scale
- **Performance Analytics**: Track and improve your SEO results

## 🚀 Quick Start

### Prerequisites

- **Node.js 20+** (required by Gemini CLI 0.38.2+)

```bash
# ⚠️ Limited file access - good for trying out the CLI
npx wordlift-cli

# ✅ Recommended for project work - full file access
npm install -g wordlift-cli
wordlift-cli

# Or clone and install locally for development
git clone https://github.com/wordlift/wordlift-cli.git
cd wordlift-cli
./install.sh
```

> **✅ Now available on npm!** You can use `npx wordlift-cli` to try it out, but **install globally** for full project integration.

### 📁 Working with Project Files

**✅ Smart Project Directory Detection**: WordLift CLI v1.0.6+ automatically:

- Detects your current working directory when you run the command
- Provides full access to local files in your project from any directory
- Uses your project's `.gemini` configuration if it exists
- Maintains proper file permissions and security

**Example Usage:**

```bash
cd /your/project/directory
wordlift-cli
> Read the file docs/strategy.md and create content based on it
```

**Previously**: npm packages had file access restrictions
**Now**: Full project integration regardless of installation method!

## 🎨 Custom Branding

WordLift CLI features custom ASCII art branding for a personalized experience:

```bash
# Automatic setup during installation
npm run setup

# Manual branding control
npm run patch-ascii    # Apply custom branding
npm run unpatch-ascii  # Reset to defaults
```

## 📖 Usage

Once installed, start the WordLift CLI and begin your AI-powered SEO workflow:

```bash
# If installed locally
./bin/wordlift-cli.js

# If installed globally
wordlift-cli

# Or run directly via npm
npx wordlift-cli

# The CLI will show the WordLift logo and launch:
🚀 WordLift CLI - Your SEO Assistant

Tips for getting started:
1. Ask questions, edit files, or run commands.
2. Be specific for the best results.
3. /help for more information.
```

### Example Commands

```bash
# Content creation
> Create a blog post about sustainable technology trends for 2025

# SEO optimization
> Analyze this article for SEO improvements and suggest meta descriptions

# Content strategy
> Help me create a content calendar for tech industry topics

# File editing
> Edit the article in output/tech-trends-2025.md to improve readability
```

## 📦 Installation Options

### Option 1: NPM (Recommended)

```bash
# Run directly (no installation needed)
npx wordlift-cli

# Or install globally
npm install -g wordlift-cli
wordlift-cli
```

### Option 2: Local Installation

```bash
git clone https://github.com/wordlift/wordlift-cli.git
cd wordlift-cli
./install.sh
./bin/wordlift-cli.js
```

### Option 3: Global Installation from Source

```bash
git clone https://github.com/wordlift/wordlift-cli.git
cd wordlift-cli
./setup-global.sh
wordlift-cli  # Available system-wide after global setup
```

## 🛠️ Configuration

Configure WordLift CLI with your Google Gemini API key:

```bash
# Set your Gemini API key
export GEMINI_API_KEY="your-api-key-here"

# Or configure interactively
wordlift-cli
> /settings
```

## 🎯 Agent Skills Support (Experimental)

WordLift CLI v1.7.0+ includes infrastructure support for **Agent Skills** - specialized expertise that the AI can activate on-demand for specific tasks.

### What are Skills?

Skills are self-contained packages of specialized knowledge and workflows. Instead of loading all expertise at once, Gemini intelligently activates skills only when needed, keeping your context focused and efficient.

### Skills Infrastructure

WordLift CLI automatically creates the `.gemini/skills/` directory in your project, enabling:
- ✅ Skills discovery and activation framework
- ✅ Progressive disclosure for efficient context management
- ✅ Consent-based skill activation
- ✅ Support for project-specific and extension-provided skills

### Installing Skills

Install the **[WordLift Gemini CLI Extension](https://geminicli.com/extensions/?name=wordliftwordlift-gemini-cli-extension)** to get specialized SEO and content optimization skills:

```bash
wordlift-cli
> /extensions install wordlift/wordlift-gemini-cli-extension
```

Or create your own skills based on the [Agent Skills](https://agentskills.io) standard.

### Managing Skills

```bash
# List available skills
> /skills list

# Disable/enable skills
> /skills disable <skill-name>
> /skills enable <skill-name>

# Reload skills after changes
> /skills reload
```

> **Note:** Skills is an experimental feature enabled by default in v1.7.0. Configure in settings: `"experimental": { "skills": true }`

## 🌐 NPM Package

```bash
# View package info
npm info wordlift-cli

# Current version
npm view wordlift-cli version
```

## 📁 Project Structure

```text
wordlift-cli/
├── bin/
│   ├── wordlift-cli.js          # Main CLI wrapper
│   └── wordlift-cli-standalone.js # Standalone version
├── docs/
│   └── ASCII_ART_PATCH.md       # ASCII art patch documentation
├── scripts/
│   ├── patch-ascii-art.js       # ASCII art patching script
│   └── setup.js                 # Setup automation
├── .gemini/
│   ├── settings.json            # Gemini CLI configuration
│   └── skills/                  # Skills directory (auto-created)
├── WORDLIFT.md                  # WordLift context file
├── wordlift-ascii-art.txt       # Custom WordLift logo
├── package.json                 # NPM package configuration
├── install.sh                   # Local installation script
├── setup-global.sh              # Global installation script
└── README.md                    # This file
```

## 🔄 Staying Updated

### For Users (Recommended)

**✅ Global Installation Update:**

```bash
# Update WordLift CLI to latest version
npm update -g wordlift-cli

# Or reinstall to get latest version
npm install -g wordlift-cli@latest
```

**✅ npx Users (Always Latest):**

```bash
# npx automatically uses the latest published version
npx wordlift-cli@latest
```

**✅ Check Current Version:**

```bash
# Check your installed version
wordlift-cli --version
# or
npm list -g wordlift-cli

# Check latest available version
npm view wordlift-cli version
```

### For Developers

**📦 Local Development:**

```bash
# Pull latest WordLift CLI changes
git pull origin main

# Update dependencies
npm install
```

**🔄 What's New in v1.7.17:**

- **Fixed MCP Discovery Error**: Automatically configures the WordLift MCP server to use a remote SSE endpoint, resolving "spawn python ENOENT" issues.
- **Improved Portability**: Better handling of settings initialization across different project folders.
- **Security Patches**: All latest security fixes from v1.7.15 included.
- Updated to **Gemini CLI 0.38.2** (latest stable release)
- Enhanced MCP auto-approval mechanisms for WordLift tools
- Full **Agent Skills** infrastructure support enabled by default

> **💡 Migration Tip**: The update is seamless! Your existing configuration and settings are preserved.

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/wordlift/wordlift-cli.git
cd wordlift-cli

# Install dependencies
npm install

# Test locally
./bin/wordlift-cli.js
```

### Making Changes

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Test thoroughly
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to your branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/wordlift/wordlift-cli/issues)
- **Documentation**: [Setup Guide](SETUP_GUIDE.md)
- **Contributing**: [Contributing Guide](CONTRIBUTING.md)
- **Agent Memory System**: [Testing Guide](input/agent_memory_system_test_instructions.md)

## 🧠 Agent Memory System

WordLift CLI includes an advanced memory system for Agent WordLift that stores guidelines, strategies, and examples in a knowledge graph using SEOVoc vocabulary. This enables the agent to:

- **Remember strategies** across sessions
- **Apply learned guidelines** consistently
- **Reference successful examples** for content creation
- **Build knowledge** over time for better performance

For testing and validation, see the [Agent Memory System Test Instructions](input/agent_memory_system_test_instructions.md).

## 🙏 Acknowledgments

- Powered by Google Gemini AI
- WordLift team for the vision and development
- Open source community for inspiration and contributions

---

Made with ❤️ by the WordLift team