wordlift-cli/README.md

WordLift CLI - A customized CLI for WordLift SEO workflows with agent memory system and smart project directory detection

# WordLift CLI 🚀

**Agent WordLift for content creation and SEO optimization** - Powered by Gemini Pro 2.5 with access to 20+ SEO tools via [WordLift MCP integration](https://docs.wordlift.io/agent-wordlift/integrations/#agent-wordlift-model-context-protocol-mcp-integration).

🤖 **[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)**

## 🎨 WordLift CLI in Action

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

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

🚀 **Agent WordLift - Content Creation & SEO Optimization**

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

- **Advanced SEO Tools**: Access to 20+ SEO tools through [WordLift MCP integration](https://docs.wordlift.io/agent-wordlift/integrations/#agent-wordlift-model-context-protocol-mcp-integration)
- **Gemini Pro 2.5**: Powered by Google's most advanced language model
- **Content Creation**: AI-driven content generation with SEO optimization
- **Knowledge Graph Integration**: Semantic SEO powered by structured data
- **Team Ready**: Designed for collaborative content creation workflows
- **Agent Memory System**: SEOVoc-based knowledge graph for storing strategies and guidelines

## 🔌 WordLift MCP Integration

The CLI leverages the **[WordLift Model Context Protocol (MCP) server](https://docs.wordlift.io/agent-wordlift/integrations/#agent-wordlift-model-context-protocol-mcp-integration)** to provide access to 20+ specialized SEO tools:

- **Semantic Analysis Tools**: Entity extraction, knowledge graph analysis
- **Content Optimization**: SEO scoring, readability analysis, keyword optimization
- **Technical SEO**: Schema markup validation, structured data generation
- **Performance Monitoring**: SERP tracking, content performance analytics
- **Research Tools**: Competitor analysis, keyword research, content gap analysis

> **Learn More**: [WordLift MCP Documentation](https://docs.wordlift.io/agent-wordlift/integrations/#agent-wordlift-model-context-protocol-mcp-integration)

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

```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 (input, output, etc.) 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 input/strategy.md and create content based on it
```

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

## 🔧 Setup & Configuration

The WordLift CLI includes optimized setup for content creation workflows with pre-configured tools and integrations.

> **Note**: Includes enhanced UI with WordLift branding as a temporary patch until [PR #2829](https://github.com/google-gemini/gemini-cli/pull/2829) adds native custom ASCII art support.

```bash
# Automatic setup (includes patch)
npm run setup

# Manual patch control
npm run patch-ascii    # Apply enhanced UI
npm run unpatch-ascii  # Restore original
```

The setup automatically detects your Gemini CLI installation and configures optimal settings for SEO workflows.

## 📖 Usage

Once installed, you can use WordLift CLI with all the SEO tools and content creation capabilities:

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

WordLift CLI uses the same configuration as Gemini CLI. Set up your API key:

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

# Or configure through the CLI
wordlift-cli
> /settings
```

## 🌐 NPM Package

**Published on npm**: [wordlift-cli](https://www.npmjs.com/package/wordlift-cli)

```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 interface
│   └── wordlift-cli-standalone.js # Standalone version
├── .gemini/
│   └── settings.json            # Gemini CLI configuration
├── 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

WordLift CLI automatically uses the latest version of Gemini CLI when run via `npx`. For local installations:

```bash
# Update Gemini CLI
npm update @google/gemini-cli -g

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

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

- Built on top of [Google's Gemini CLI](https://github.com/google-gemini/gemini-cli)
- WordLift team for the vision and platform
- Open source community for inspiration and contributions

---

Made with ❤️ by the WordLift team