gyst

---

What is gyst?

gyst is an all-in-one AI developer CLI that lives in your terminal. It translates natural language to git commands, reviews your code with auto-fix, roasts bad code, explains cryptic errors, generates standups from git history, writes READMEs, and explains codebases — all powered by the AI provider of your choice.

# Interactive setup — get started in 2 minutes
$ gyst setup

# Translate English to git
$ gyst git "undo my last commit but keep the changes"
🔧 git reset --soft HEAD~1

# AI-generated commit messages
$ gyst commit
📝 feat(auth): add OAuth2 login flow

# AI code review with one-click fixes
$ gyst review src/ --fix
🔴 SQL Injection in auth.ts:42  →  auto-fixed ✓

# Generate PR descriptions
$ gyst pr
📋 Add OAuth2 Authentication — Summary, Changes, Testing checklist

# Get roasted
$ gyst roast index.js --severity brutal
💀 Using var in 2026? This code is a time capsule.

# Explain any error
$ npm run build 2>&1 | gyst wtf
💡 Your PostCSS config references a plugin that isn't installed...

# Generate standup from git history
$ gyst standup --format slack
📋 *What I did:* Implemented auth flow, fixed 3 bugs...

# Generate changelog from git history
$ gyst changelog --since v0.1.0
📋 ## [0.2.0] — Added, Changed, Fixed sections

Installation

# npm
npm install -g gyst-ai

# pnpm
pnpm add -g gyst-ai

# yarn
yarn global add gyst-ai

Requirements: Node.js >= 20

Quick Start

# 1. Interactive setup (recommended)
gyst setup

# Or set your API key manually
export ANTHROPIC_API_KEY=sk-ant-...

# 2. Start using it
gyst git "show me what changed this week"
gyst commit
gyst review src/
gyst pr
gyst roast app.js
gyst wtf "ECONNREFUSED 127.0.0.1:5432"
gyst standup
gyst changelog
gyst readme --dry-run
gyst explain src/core/

Commands

gyst setup — Interactive Setup Wizard

Get up and running in under 2 minutes. Walks you through provider selection, API key configuration, model choice, and preferences.

$ gyst setup

# Non-interactive mode for CI/scripts
$ gyst setup --provider anthropic --key sk-ant-... --non-interactive

Features:

• Choose from 6 AI providers (Anthropic, OpenAI, Google, Groq, DeepSeek, Ollama)
• Validates your API key before saving
• Sets default model and preferences
• Add multiple providers in one session
• First-run detection: prompts you to run gyst setup if no keys are configured

---

gyst git — Natural Language Git

Translates plain English instructions into the exact git command you need. Understands your repo context (current branch, status, remotes, stash) and warns you before running anything destructive.

$ gyst git "squash the last 3 commits"
┌─ 🔧 Git Command ───────────────────────┐
│ git rebase -i HEAD~3                    │
│ Interactively squash the last 3 commits │
└─────────────────────────────────────────┘
  Run this command? (Y/n):

Features:

• Reads your repo state (branch, status, log, remotes, stash count)
• Warns about destructive commands (requires typing yes instead of Y)
• Shows alternative commands when applicable
• Strips markdown fences from AI response for reliable parsing

---

gyst commit — AI-Generated Commit Messages

Analyzes your staged changes and generates a conventional commit message. Accept, edit in $EDITOR, or cancel.

# Generate commit message from staged changes
$ gyst commit

# Stage everything and commit
$ gyst commit --all

# Subject line only (no body)
$ gyst commit --short

Features:

• Conventional Commits format (feat|fix|refactor|docs|test|chore)
• Accept / Edit / Cancel flow
• Opens $EDITOR for manual editing
• Truncates large diffs to stay within context limits

---

gyst pr — AI-Generated PR Descriptions

Generates a complete PR description from your branch's commits and diffs.

# Generate PR description
$ gyst pr

# Specify base branch
$ gyst pr --base develop

# Copy to clipboard
$ gyst pr --copy

# Create PR via GitHub CLI
$ gyst pr --open

# Mark as draft
$ gyst pr --draft

Features:

• Auto-detects base branch (main/master)
• Structured output: Summary, Changes, Testing checklist
• Clipboard support (macOS, Linux, Windows)
• Direct gh pr create integration with --open

---

gyst changelog — Generate Changelogs

Generates a changelog from your git history in Keep a Changelog format.

# Generate from last tag to HEAD
$ gyst changelog

# From a specific tag/commit
$ gyst changelog --since v0.1.0

# Set version number
$ gyst changelog --version 1.0.0

# Preview without writing
$ gyst changelog --dry-run

# JSON output
$ gyst changelog --format json

Features:

• Auto-detects the last git tag as range start
• Keep a Changelog format (Added/Changed/Fixed/Removed/Security)
• Prepends to existing CHANGELOG.md
• JSON output for automation

---

gyst review — AI Code Review with Auto-Fix

Professional code review that finds real bugs, security issues, and anti-patterns — then provides exact code replacements you can auto-apply.

# Review a file
$ gyst review src/api/auth.ts

# Review an entire directory
$ gyst review src/

# Auto-apply all fixes
$ gyst review src/ --fix

# Only show critical and warning severity
$ gyst review src/ --severity warning

Features:

• 4 severity levels: critical, warning, suggestion, nitpick
• Exact currentCode → suggestedCode replacements for auto-fix
• Fixes applied in reverse line order to preserve positions
• Confirms before writing files, suggests git diff after
• --json output for CI integration

---

gyst roast — Code Roasting

Get a brutally honest (and funny) review of your code. Three severity levels from gentle encouragement to full Gordon Ramsay.

$ gyst roast src/utils.ts --severity brutal

💀 Roast mode: BRUTAL

🔥 Code Roast: utils.ts

Line 1: `var express = require('express')` — Using var in 2026?
This code is a time capsule. Someone call the archaeology department.

📊 Overall: 3/10
🎤 Final Verdict: This code doesn't just have bugs — it IS the bug.

Severity levels:

• gentle — Constructive with light humor
• medium — Comedy roast meets code review (default)
• brutal — Full Gordon Ramsay, no mercy

---

gyst wtf — Error Explanation

Explain any error message and get copy-paste-ready fix commands. Supports piping directly from your build tools.

# Pass an error directly
$ gyst wtf "ENOENT: no such file or directory, open './config.json'"

# Pipe from any command
$ npm run build 2>&1 | gyst wtf
$ cargo build 2>&1 | gyst wtf
$ python app.py 2>&1 | gyst wtf

Features:

• Detects your project type for framework-specific advice
• Streaming output — see the explanation as it generates
• Supports stdin piping (!process.stdin.isTTY detection)

---

gyst standup — Standup Generation

Generate standup updates from your git history. Supports multiple output formats.

# Default: beautiful terminal output
$ gyst standup

# Slack-formatted for pasting
$ gyst standup --format slack

# JSON for automation
$ gyst standup --format json

# Look back 3 days
$ gyst standup --days 3

# Custom time range
$ gyst standup --since "last monday"

Output includes:

• What you did (grouped by logical work items)
• What's next (inferred from patterns)
• Blockers (if any)
• Stats: commits, files changed, insertions, deletions

---

gyst readme — README Generation

Analyzes your entire codebase and generates a comprehensive README.

# Generate (saves as README.generated.md if README.md exists)
$ gyst readme

# Preview without writing
$ gyst readme --dry-run

# Different styles
$ gyst readme --style minimal    # Just the essentials
$ gyst readme --style detailed   # Full documentation (default)
$ gyst readme --style startup    # Pitch-style, sells the project

# Custom output path
$ gyst readme --output DOCS.md

---

gyst explain — Code Explanation

Explain what code does in plain English. Works with single files or entire directories.

# Explain a file
$ gyst explain src/core/ai.ts

# Explain a directory (reads up to 8 files)
$ gyst explain src/core/

Covers:

• Purpose and problem solved
• Key logic and data flow
• Design patterns recognized
• Dependencies and gotchas

---

gyst config — Configuration

Manage API keys, default models, and preferences.

# Show current config
$ gyst config show

# Set API keys
$ gyst config set key anthropic sk-ant-api03-...
$ gyst config set key openai sk-...
$ gyst config set key google AIza...
$ gyst config set key groq gsk-...

# Set default model
$ gyst config set model gpt-4o
$ gyst config set model claude-opus

# Set preferences
$ gyst config set preference roastSeverity brutal
$ gyst config set preference standupDays 3

# Reset everything
$ gyst config reset

Providers

gyst supports 6 AI providers out of the box. Set your preferred provider's API key and go.

Provider	Models	Env Variable	Best For
Anthropic	claude-sonnet, claude-haiku, claude-opus	ANTHROPIC_API_KEY	Best overall quality
OpenAI	gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini	OPENAI_API_KEY	Fastest responses
Google	gemini-pro, gemini-flash	GOOGLE_GENERATIVE_AI_API_KEY	Free tier available
Groq	llama3 (Llama 3.1 70B)	GROQ_API_KEY	Fastest open model
DeepSeek	deepseek	DEEPSEEK_API_KEY	Budget-friendly
Ollama	local:<model-name>	—	Fully offline / private

Using a Specific Provider

# Use a specific model
$ gyst git "status" --model gpt-4o

# Use local Ollama
$ gyst git "status" --local

# Override provider
$ gyst git "status" --provider openai

Provider Key Resolution

1. Environment variable (e.g., ANTHROPIC_API_KEY)
2. Config file (~/.gyst/config.json via gyst config set key)
3. Helpful error message pointing to gyst config set key

Configuration

Config is stored at ~/.gyst/config.json. You can edit it directly or use gyst config set.

{
  "defaultModel": "claude-sonnet",
  "defaultProvider": "anthropic",
  "keys": {
    "anthropic": "sk-ant-..."
  },
  "ollamaBaseUrl": "http://localhost:11434",
  "preferences": {
    "roastSeverity": "medium",
    "standupDays": 1,
    "gitAutoExecute": false
  }
}

Global Flags

These flags work with every command:

Flag	Description
-m, --model <model>	AI model to use (e.g., claude-sonnet, gpt-4o, local:llama3.2)
-p, --provider <provider>	Override provider (anthropic, openai, google, groq, ollama, deepseek)
--local	Use local Ollama mo