Skip to content

usage.md

Latest commit

 

History

History
218 lines (154 loc) · 7.28 KB

usage.md

File metadata and controls

218 lines (154 loc) · 7.28 KB

Usage

← Back to README

Persona Modes

Persona ID Description
Gentleman gentleman Teaching-oriented mentor persona — pushes back on bad practices, explains the why
Neutral neutral Same teacher, same philosophy, no regional language — warm and professional
Custom custom Keep your existing persona/config unmanaged — gentle-ai does not inject a persona

custom is a compatibility/ownership choice, not a persona editor. Use it when you already have your own persona instructions and want gentle-ai to leave them alone.

Interactive TUI

Just run it — the Bubbletea TUI guides you through agent selection, components, skills, presets, and managed uninstall flows:

gentle-ai

The uninstall flow is also available from the TUI menu. It lets you:

  • select one or more configured agents
  • select which managed components to remove (for example sdd, persona, or context7)
  • confirm the exact uninstall scope before applying changes

Before any managed file is modified, gentle-ai creates a backup snapshot so the configuration can be restored later if needed.

CLI Commands

install

First-time setup — detects your tools, configures agents, injects all components:

# Full ecosystem for multiple agents
gentle-ai install \
  --agent claude-code,opencode,gemini-cli \
  --preset full-gentleman

# Minimal setup for Cursor
gentle-ai install \
  --agent cursor \
  --preset minimal

# Pick specific components and skills
gentle-ai install \
  --agent claude-code \
  --component engram,sdd,skills,context7,persona,permissions \
  --skill go-testing,skill-creator,branch-pr,issue-creation \
  --persona gentleman

# Dry-run first (preview plan without applying changes)
gentle-ai install --dry-run \
  --agent claude-code,opencode \
  --preset full-gentleman

sync

Refresh managed assets to the current version. Use after brew upgrade gentle-ai or when you want your local configs aligned with the latest release. Does NOT reinstall binaries (engram, GGA) — only updates prompt content, skills, MCP configs, and SDD orchestrators.

# Sync all installed agents
gentle-ai sync

# Sync specific agents only
gentle-ai sync --agent cursor --agent windsurf

# Sync a specific component
gentle-ai sync --component sdd
gentle-ai sync --component skills
gentle-ai sync --component engram

Sync is safe and idempotent — running it twice produces no changes the second time.

uninstall

Remove only the gentle-ai managed configuration from one or more agents. This does not uninstall external packages or binaries — it removes managed prompt sections, MCP entries, skills/config fragments, and other managed files, then updates state.json accordingly.

Before any change is applied, gentle-ai creates a backup snapshot of the affected files.

# Partial uninstall for specific agents
gentle-ai uninstall \
  --agent claude-code \
  --agent opencode

# Partial uninstall for specific components only
gentle-ai uninstall \
  --agent claude-code \
  --component sdd,persona,context7

# Complete uninstall of managed config from all supported agents
gentle-ai uninstall --all

# Skip confirmation prompt
gentle-ai uninstall --agent cursor --component skills --yes

If no --component flag is provided for a partial uninstall, gentle-ai removes all managed uninstallable components for the selected agent set.

update / upgrade

Check for and install new versions of gentle-ai itself:

# Check if a newer version is available
gentle-ai update

# Upgrade to the latest release (downloads new binary, replaces current)
gentle-ai upgrade

After upgrading, run gentle-ai sync to refresh all managed assets to the new version's content.

version

gentle-ai version
gentle-ai --version
gentle-ai -v

CLI Flags (install)

Flag Description
--agent, --agents Agents to configure (comma-separated)
--component, --components Components to install (comma-separated)
--skill, --skills Skills to install (comma-separated)
--persona Persona mode: gentleman, neutral, custom (custom keeps your existing persona unmanaged)
--preset Preset: full-gentleman, ecosystem-only, minimal, custom (custom means manual component/skill selection)
--dry-run Preview the install plan without applying changes

CLI Flags (sync)

Flag Description
--agent, --agents Agents to sync (defaults to all installed agents)
--component Sync a specific component only: sdd, engram, context7, skills, gga, permissions, theme
--profile Create or update an SDD profile: name:provider/model (sets the default model for all phases)
--profile-phase Override a specific phase in a profile: name:phase:provider/model
--sdd-profile-strategy OpenCode profile sync strategy: generated-multi or external-single-active
--include-permissions Include permissions sync (opt-in)
--include-theme Include theme sync (opt-in)

Profile examples:

# Create a "cheap" profile using a free model for all phases
gentle-ai sync --profile cheap:openrouter/qwen/qwen3-30b-a3b:free

# Override the design phase to use a stronger model
gentle-ai sync --profile-phase cheap:sdd-design:anthropic/claude-sonnet-4-20250514

# Create multiple profiles in one command
gentle-ai sync \
  --profile cheap:openrouter/qwen/qwen3-30b-a3b:free \
  --profile premium:anthropic/claude-sonnet-4-20250514

# Use compatibility mode with an external OpenCode profile manager
gentle-ai sync --agent opencode --sdd-profile-strategy external-single-active

See OpenCode SDD Profiles for the full guide.

CLI Flags (uninstall)

Flag Description
--agent, --agents Agents to uninstall managed config from (required unless using --all)
--component, --components Managed components to remove only from the selected agents
--all Remove managed configuration from all supported agents
--yes, -y Skip the confirmation prompt

Typical Workflow

# First time: install everything
brew install gentleman-programming/tap/gentle-ai
gentle-ai install --agent claude-code,cursor --preset full-gentleman

# After a new release: upgrade + sync
brew upgrade gentle-ai
gentle-ai sync

# Remove only managed SDD + persona config from one agent
gentle-ai uninstall --agent claude-code --component sdd,persona

# Adding a new agent later
gentle-ai install --agent windsurf --preset full-gentleman

Dependency Management

gentle-ai auto-detects prerequisites before installation and provides platform-specific guidance:

  • Detected tools: git, curl, node, npm, brew, go
  • Version checks: validates minimum versions where applicable
  • Platform-aware hints: suggests brew install, apt install, pacman -S, dnf install, or winget install depending on your OS
  • Node LTS alignment: on apt/dnf systems, Node.js hints use NodeSource LTS bootstrap before package install
  • Dependency-first approach: detects what's installed, calculates what's needed, shows the full dependency tree before installing anything, then verifies each dependency after installation