gemini-cli-job

Gemini CLI Job

AI-powered automation jobs made simple. Generate reports, release notes, and team updates automatically.

A clean CLI tool for creating and running automated AI jobs using Google's Gemini. Perfect for teams who want to automate routine documentation and reporting tasks.

Installation

npm install -g gemini-cli-job

Quick Start

1. Setup (1 minute)

Run the interactive setup wizard:

gjob setup

This will:

• Configure your Google Cloud Project and Gemini model
• Create your first job from built-in templates
• Generate sample template files for customization
• Set up scheduling (optional)

2. Customize Template Files

Edit the generated template files in ~/.gemini-cli-job/context/:

• about.md - Your organization/team information
• products.md - Your products and services
• workflows.md - Your development processes
• *-rules.md - Guidelines for different report types

3. Run Your First Job

# Test immediately
gjob list
gjob run my-project-release-notes

# Or start the scheduler for automatic runs
gjob start

Commands

Basic Usage

• gjob - Start interactive scheduler
• gjob -j <job-name> - Run specific job once
• gjob list - List all configured jobs
• gjob --help - Show all available commands

Memory Management

Jobs automatically maintain persistent memory across runs to track state like last update times, versions, etc.

• gjob memory list - List all jobs with stored memory
• gjob memory show <job-name> - View memory content for a specific job
• gjob memory clear <job-name> - Clear stored memory for a job

Memory is automatically enabled for all jobs. When jobs run, they can access and update key-value pairs that persist between runs. This is useful for tracking timestamps, version numbers, or any other state that needs to be remembered.

Example job configuration:

{
  "jobName": "version-tracker",
  "enabled": true,
  "schedules": ["0 9 * * *"],
  "promptConfig": {
    "contextFiles": ["context/about.md"],
    "customPrompt": "Track version updates and remember the last checked version"
  }
}

The Gemini AI can update memory by including a jobMemory object in its JSON response:

{
  "jobResult": "Generated weekly report with 5 new features documented.",
  "jobMemory": {
    "lastUpdatedTime": "2025-08-27T15:30:00Z",
    "featuresProcessed": 5,
    "nextDeadline": "2025-09-01"
  }
}

Robust Response Handling: The system can handle various output formats:

• Pure JSON responses
• JSON mixed with other logs/text
• Plain text responses (automatic fallback)
• Invalid or malformed responses (graceful error handling)

Command Aliases: You can use gjob, gemini-job, or gemini-cli-job - they all work the same.

Features

• 🎯 Template-Based Jobs - Flexible job system using customizable templates
• 🔧 1-Minute Setup - Interactive wizard gets you started instantly
• 📅 Smart Scheduling - Cron-based automation with manual override
• 📝 Context-Aware - Uses your team info for better AI outputs
• ⚡ Lightweight - Single purpose, minimal dependencies

Prerequisites

• Gemini CLI installed and configured
• Google Cloud Project with Gemini API access
• Node.js 18+

Configuration

Job Configuration

Your jobs are stored in ~/.gemini-cli-job/config.json. Example:

{
  "googleCloudProject": "your-gcp-project-id",
  "geminiOptions": {
    "model": "gemini-2.0-flash"
  },
  "jobs": [
    {
      "jobName": "weekly-team-update",
      "enabled": true,
      "schedules": ["0 17 * * 5"],
      "promptConfig": {
        "contextFiles": [
          "context/about.md",
          "context/weekly-update-rules.md"
        ],
        "customPrompt": "Focus on engineering team achievements and blockers"
      },
      "geminiOptions": {
        "model": "gemini-2.5-flash"
      }
    }
  ]
}

Gemini Options Configuration

You can configure Google Cloud Project and Gemini model settings globally in your config.json, with optional per-job overrides. Global settings take priority over environment variables, and job-specific settings override global settings:

{
  "googleCloudProject": "your-gcp-project-id",
  "geminiOptions": {
    "model": "gemini-2.0-flash"
  },
  "jobs": [
    {
      "jobName": "standard-report",
      "enabled": true,
      "schedules": ["0 9 * * 1"],
      "promptConfig": {
        "contextFiles": ["context/weekly-rules.md"],
        "customPrompt": "Generate weekly report"
      }
    },
    {
      "jobName": "creative-content",
      "enabled": true,
      "schedules": ["0 14 * * 3"],
      "promptConfig": {
        "contextFiles": ["context/content-rules.md"],
        "customPrompt": "Generate creative content"
      },
      "geminiOptions": {
        "model": "gemini-2.5-flash"
      }
    }
  ]
}

Available configuration options:

• googleCloudProject - Google Cloud Project ID (overrides GOOGLE_CLOUD_PROJECT environment variable)
• geminiOptions.model - Gemini model to use (overrides GEMINI_MODEL environment variable)
• geminiOptions.timeoutMs - Timeout in milliseconds for job execution (default: 300000 = 5 minutes)

Example with custom timeout:

{
  "jobName": "long-running-analysis",
  "enabled": true,
  "schedules": ["0 2 * * 1"],
  "promptConfig": {
    "contextFiles": ["context/analysis-rules.md"],
    "customPrompt": "Perform comprehensive data analysis"
  },
  "geminiOptions": {
    "model": "gemini-2.5-flash",
    "timeoutMs": 900000
  }
}

Note: Advanced options like temperature and maxTokens are not currently supported by Gemini CLI

Environment Variables

Set these in your .env file:

GOOGLE_CLOUD_PROJECT=your-gcp-project-id
GEMINI_MODEL=gemini-1.5-flash

# Optional: Set custom config file path
GJOB_CONFIG_FILE=/path/to/your/config.json

Config File Priority

The CLI uses the following priority order for configuration:

• CLI Option: --config /path/to/config.json (highest priority)
• Environment Variable: GJOB_CONFIG_FILE=/path/to/config.json
• Default: ~/.gemini-cli-job/config.json (lowest priority)

Examples:

# Set environment variable once
export GJOB_CONFIG_FILE="/path/to/your/config.json"

# Use commands without --config
gjob list
gjob start
gjob run my-job

# Override environment variable when needed
gjob --config /other/config.json list

Authentication Setup

Before running jobs, ensure proper authentication:

• Install Google Cloud CLI: gcloud auth application-default login
• Verify project access: gcloud config set project your-gcp-project-id
• Enable Gemini API: Enable the Generative AI API in your Google Cloud project
• Test authentication: gemini --help (should work without errors)

Common authentication issues:

• 404 Requested entity was not found → Check project ID and API access
• Permission denied → Verify your account has Generative AI permissions
• Invalid credentials → Run gcloud auth application-default login again

Template Files

Customize files in ~/.gemini-cli-job/context/ to improve AI output quality:

• about.md - Your organization, team, mission
• products.md - Products, services, tech stack
• workflows.md - Development processes, tools
• *-rules.md - Specific formatting rules for each job type

Common Use Cases

Automated Release Notes

• Schedule: Monday mornings after deployments
• Context: Include product info, release formatting rules
• Output: Structured release notes for stakeholders

Team Weekly Updates

• Schedule: Friday afternoons
• Context: Team member info, current project focus
• Output: Progress summary for management

Daily Standup Prep

• Schedule: Before daily standups
• Context: Sprint goals, team workflows
• Output: Formatted updates for each team member

Troubleshooting

Job Not Running?

• Check if job is enabled: gjob list
• Verify environment: Check .env file has correct GOOGLE_CLOUD_PROJECT
• Test Gemini CLI: Run gemini --version to confirm it's installed

Gemini CLI Not Found (Windows)?

If you see spawn gemini ENOENT error on Windows:

• Install Gemini CLI: npm install -g @google/gemini-cli
• Restart terminal after installation to refresh PATH
• Test installation: Run gemini --help in a new terminal
• Check PATH: Ensure Node.js global packages are in PATH
• Alternative: Try running from Command Prompt as Administrator

Poor AI Output Quality?

• Update context files - Add specific info about your team/products
• Improve job parameters - Be more specific in context parameters
• Check context loading - Ensure context files exist and have content

Scheduling Issues?

• Verify cron format - Use crontab.guru to validate
• Check timezone - Schedules use system timezone
• Enable jobs - Make sure "enabled": true in config

Support

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions or share context templates

Contributing

See CONTRIBUTING.md for development setup, architecture details, and contribution guidelines.

License

MIT License - see LICENSE file for details.