Ginvo Documentation

Before you start

Extract the download to a permanent local folder. Ginvo requires Windows PowerShell 5.1 and Git for Windows. Google Sheets and LLM features are optional. Ginvo keeps its configuration, drafts, caches, and encrypted secrets under `%LOCALAPPDATA%\Ginvo`.

Install, open, and get help

# Register the short command once, then open a new PowerShell window.
& "C:\Path\To\Ginvo\Ginvo.cmd" install

# Launch the desktop UI from a repository; it preselects that repository.
& "C:\Path\To\Ginvo\Ginvo.cmd"

# Command reference
ginvo help
ginvo ui [--month YYYY-MM]
ginvo config

Connect a client repository

Connect maps a repository to a client and optionally saves rates and minimum monthly hours. Run it once per client repository.

ginvo connect `
  --id client-id `
  --name "Client Name" `
  --sheet "Client Name" `
  --repo C:\Projects\client-project `
  --currency ZAR `
  --minimum 25 `
  --plan-rate 750 `
  --dev-rate 1100 `
  --des-rate 600 `
  --write-rate 800 `
  --maint-rate 850

Create and review drafts

A draft collects Git evidence and keeps manual/imported work intact. `draft` can target a client directly; `generate` resolves the client from the current repository.

# No LLM: best first test
ginvo draft --month 2026-07 --no-llm

# Optional explicit client and workbook
ginvo draft --month 2026-07 --client client-id --spreadsheet GOOGLE_SHEET_ID

# From inside a connected repository
ginvo generate 2026-07 --no-llm
ginvo generate --month 2026-07

# Review in the desktop application
ginvo ui --month 2026-07

Timer commands

Timers are optional and supplement, rather than replace, Git evidence. When a repository is connected, the client is inferred from the current folder.

ginvo timer start --client client-id --note "Investigate checkout issue"
ginvo timer stop --type dev
ginvo timer status

AI adjustment commands

Ginvo always previews an adjustment first. It changes nothing until `--apply` is supplied.

# Preview
ginvo adjust --month 2026-07 --client client-id --instruction "Spread it out to reach 25.4 hours"

# Apply only after review
ginvo adjust --month 2026-07 --client client-id --instruction "Spread it out to reach 25.4 hours" --apply

# Deterministic preview without an LLM
ginvo adjust --month 2026-07 --client client-id --instruction "Reach 25.4 hours" --no-llm

Google Sheets commands

Google integration is optional. First configure your own OAuth client or service account locally. Share the destination folder and template with a service account before using it. The source credentials are encrypted with Windows DPAPI and are not copied into Ginvo.

ginvo auth google
ginvo auth google-service --file C:\Secure\service-account.json

# Link a workbook for the current month or as historical context
ginvo link-sheet --spreadsheet CURRENT_MONTH_ID
ginvo link-sheet --historical --client client-id --spreadsheet OLD_WORKBOOK_ID

# Export a reviewed draft
ginvo export --month 2026-07
ginvo export --month 2026-07 --spreadsheet CURRENT_MONTH_ID

LLM setup and privacy

Run `auth llm` to store your own API key locally with Windows DPAPI. Git evidence remains the source for dates and durations. Ginvo redacts credential-like patch lines and excludes sensitive paths from LLM evidence. Do not provide an agent with API keys, Google credential JSON, `%LOCALAPPDATA%\Ginvo` contents, or private repository credentials.

ginvo auth llm

Agent / LLM hand-off

Paste this documentation page into an agent’s instructions or use Copy for LLM. It gives the agent the public canonical URL and the exact command surface. A local agent can run Ginvo only after the person installs it and connects their own repository; it should use `--no-llm` and preview-only operations first.