workctl

workctl syncs Kawari timesheets to Jira Cloud worklogs.

Interactive workctl commands use Clack for prompts, progress, warnings, and results. Command flags remain available for scripts and non-interactive use.

Quick Start

Prerequisites: Node.js >=22, a Jira Cloud API token, and access to your Kawari timesheet.

npm install -g @geneverse/workctl
workctl browsers install
workctl setup
workctl jira preview
workctl jira sync

Run workctl for the interactive hub, or use direct subcommands when you want a specific capability immediately. The hub lists every built-in capability; advanced workflows are hidden until Advanced mode is enabled.

preview is read-only. Use it first to confirm what will be created in Jira. sync asks for approval before writing worklogs.

Configuration

Run workctl setup for the normal first-time setup. It configures Jira sync, verifies the result, and writes a private user configuration file.

Use workctl jira configure later if you need to edit Jira credentials, service defaults, or other Jira sync settings.

On macOS and Linux, configuration is stored at:

~/.config/workctl/config.json

On Windows, it is stored under:

%APPDATA%\workctl\config.json

The Jira API token is stored as plain text in that user config file. Use workctl only on a trusted personal workstation.

Environment variables override config file values field by field:

| Config field | Environment override | |---|---| | jiraBaseUrl | JIRA_BASE_URL | | jiraEmail | JIRA_EMAIL | | jiraApiToken | JIRA_API_TOKEN | | timesheetUrl | TIMESHEET_URL | | timezone | TZ |

workctl does not load .env files. Use workctl jira config show to inspect effective values and where they came from. The token is always redacted.

Commands

| Command | Purpose | |---|---| | workctl | Open the interactive hub for core workflows | | workctl setup | Configure and verify Jira sync | | workctl browsers install | Install the Playwright Chromium browser used for Kawari scraping | | workctl jira preview [--from YYYY-MM-DD] [--to YYYY-MM-DD] | Show what would be synced without writing to Jira | | workctl jira sync [--from YYYY-MM-DD] [--to YYYY-MM-DD] | Scrape Kawari, preview, ask for approval, create Jira worklogs, and verify them | | workctl kawari | Interactively choose a Kawari capability, starting with timesheet export | | workctl kawari export-timesheet [--from YYYY-MM-DD] [--to YYYY-MM-DD] | Direct, automation-compatible Kawari timesheet export | | workctl kawari analyze-cv <bundle-or-csv> [--model ID] | Interactively review an exported timesheet with OpenRouter | | workctl git rewrite-date [--rule DATE[@DAYS]@HOURS] [--base REF] [--new-branch] [--dry-run] [--yes] | Preview and safely rewrite timestamps for unpublished linear commits | | workctl ai | Interactively configure OpenRouter access and choose the default AI model | | workctl jira follow-ups [--project KEY] [--sprint ID\|all] [--export csv\|json] | Find done Jira issues whose linked issues are not done | | workctl doctor [--capability jira] [--json] | Check config, dependencies, credentials, network, and local state | | workctl jira rollback [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--issue KEY] [--dry-run] | Delete matching tool-managed worklogs after typed approval | | workctl update | Update the global @geneverse/workctl install after approval | | workctl advanced enable\|disable\|status | Manage visibility of advanced workflows in the interactive hub |

When dates are omitted, Jira sync uses the current calendar month in Asia/Bangkok. Explicit date ranges must stay within one calendar month.

Interactive navigation

Interactive capability menus stay open after an action finishes. Choose Back to return to the previous menu, or press Ctrl+C at a menu for the same result; use Exit from the main workctl menu. Cancelling a form discards only values that have not yet been saved and returns to its menu.

Rewriting local commit dates

workctl git rewrite-date is for local work that has not been pushed. It selects commits since the current branch's upstream merge-base, shows a deterministic preview, then requires you to type REWRITE before changing history. It normally creates a backup/rewrite-date-... recovery branch first.

workctl git rewrite-date --from 2026-07-11 --to 2026-07-12 --hours 08:30-17:30 --dry-run
workctl git rewrite-date --from 2026-07-11 --to 2026-07-12 --hours 17:30+ --yes

# Multiple allowed windows: Saturday daytime and weekday evenings
workctl git rewrite-date \
  --rule '2026-07-11@Sat@09:00+' \
  --rule '2026-07-13..2026-07-17@Mon-Fri@19:00+' \
  --dry-run

# Preserve the current feature branch and inspect rewritten commits on a new local branch.
workctl git rewrite-date --from 2026-07-11 --to 2026-07-12 --hours 08:30-17:30 --new-branch

--rule accepts DATE@HOURS for every day, or DATE..DATE@DAYS@HOURS to filter weekdays. Use Mon-Fri, Sat,Sun, or individual short weekday names. The older --from, --to, and --hours flags remain available for one all-days rule, but cannot be mixed with --rule.

The command refuses dirty worktrees, published/no-longer-unpublished commits, merge commits, and signed commits. --new-branch creates and checks out a local rewrite-date/<source>-<UTC timestamp> result branch without pushing; the source branch remains the recovery point. On a branch without an upstream, it uses the remote default branch when available. In a local-only interactive repository it asks you to select an ancestor branch; for automation, supply a base explicitly, for example --base main.

Git history rewriting is an advanced workflow and is hidden from bare workctl by default. This is a usability guardrail, not access control: direct commands remain available. Enable its menu entry on this machine with:

workctl advanced enable

Kawari history exports

workctl is the recommended interactive entry point. It presents the core actions through Clack, beginning with AI, Kawari, Setup, Doctor, and Update. Direct capability commands remain available for scripts and CI.

workctl kawari remains available as a focused interactive entry point for Kawari actions. workctl kawari export-timesheet remains available for scripts and CI.

The export asks for inclusive From and To dates through Clack when flags are omitted. It supports ranges across months, opens a persistent browser for one manual Kawari login when necessary, and does not write to Kawari or Jira. The first use migrates the existing Kawari URL from the Jira configuration into Kawari's capability configuration automatically.

Each export is written with private file permissions to a date-range-named bundle beneath the directory where you run the command. Repeated exports for the same range receive a numeric suffix instead of overwriting prior output:

exports/kawari/2026-03-01_to_2026-03-31/
  raw.json
  timesheet.csv
  timesheet.md

CSV and Markdown contain date, project, entry, and hours. The exporter scrolls through the Kawari grid to read every rendered project. Rows with zero hours are excluded from the primary exports. A task without a detectable Kawari project header is exported with project unknown and reported as a warning so the scraper can be improved without losing the record. raw.json also records per-month grid diagnostics and export totals.

After an interactive export, workctl can review detected Jira projects and send only timesheet.csv to OpenRouter for a CV analysis. Set an AI key with workctl ai. It securely configures and verifies the API key, then lets you search and choose a text model from OpenRouter. The resulting cv-project-summary.md is written only after you review the streamed AI chat and enter /accept. If AI is not ready, workctl writes a manual prompt without sending the CSV.

Updating

workctl update

You can also update directly with npm:

npm update -g @geneverse/workctl

Uninstall

npm uninstall -g @geneverse/workctl

Contributing and security

See the contribution guide for local development and verification. Report vulnerabilities through the security policy, not through a public issue.