Loading
Back to Hourfield
Good tools
HOURFIELD FOR TOOLS & AGENTS
Good tools
work together.
The hourfield command line gives local scripts and assistants the same reach as the Mac app, with stable JSON and the app still in charge of every save.
AGENT SKILL / 1.0.0
Teach your agent Hourfield.
Install the hourfield skill in Codex or Claude Code. It teaches your agent to discover your installed CLI, read before changing records, preview edits, and handle conflicts and retries.
The download contains instructions only: hourfield/SKILL.md. You also need a compatible Hourfield Mac build and the signed Mac CLI. Installing the skill does not install the app or grant beta access.
Read the skill first, then choose your local agent below and paste the commands into Terminal on your Mac. They check the download's SHA-256 and stop if an hourfield skill already exists. Review or move your existing skill yourself before updating it.
Codex~/.codex/skills/hourfield
(
set -eu
skill_parent="$HOME/.codex/skills"
skill_target="$skill_parent/hourfield"
if [ -e "$skill_target" ] || [ -L "$skill_target" ]; then
printf '%s\n' "Already exists: $skill_target. Review it before updating." >&2
exit 1
fi
skill_tmp="$(mktemp -d)"
trap 'rm -rf "$skill_tmp"' EXIT
curl -fsSL https://tieoff.app/apps/hourfield/skills/hourfield.zip -o "$skill_tmp/hourfield.zip"
printf '%s %s\n' 'a864a9f9a5e499f78f7afb457cafd406ec5e4dcc47a790fab4125965820cb254' "$skill_tmp/hourfield.zip" | shasum -a 256 -c -
unzip -q "$skill_tmp/hourfield.zip" -d "$skill_tmp"
mkdir -p "$skill_parent"
mkdir "$skill_target"
cp "$skill_tmp/hourfield/SKILL.md" "$skill_target/SKILL.md"
printf '%s\n' "Installed: $skill_target/SKILL.md"
)Claude Code~/.claude/skills/hourfield
(
set -eu
skill_parent="$HOME/.claude/skills"
skill_target="$skill_parent/hourfield"
if [ -e "$skill_target" ] || [ -L "$skill_target" ]; then
printf '%s\n' "Already exists: $skill_target. Review it before updating." >&2
exit 1
fi
skill_tmp="$(mktemp -d)"
trap 'rm -rf "$skill_tmp"' EXIT
curl -fsSL https://tieoff.app/apps/hourfield/skills/hourfield.zip -o "$skill_tmp/hourfield.zip"
printf '%s %s\n' 'a864a9f9a5e499f78f7afb457cafd406ec5e4dcc47a790fab4125965820cb254' "$skill_tmp/hourfield.zip" | shasum -a 256 -c -
unzip -q "$skill_tmp/hourfield.zip" -d "$skill_tmp"
mkdir -p "$skill_parent"
mkdir "$skill_target"
cp "$skill_tmp/hourfield/SKILL.md" "$skill_target/SKILL.md"
printf '%s\n' "Installed: $skill_target/SKILL.md"
)Start a new local session after installing. In Codex, ask $hourfield to review this week's time. In Claude Code, use /hourfield. The skill starts with readiness and capability checks; it will explain what is missing if the app or CLI is unavailable.
ZIP SHA-256 a864a9f9a5e499f78f7afb457cafd406ec5e4dcc47a790fab4125965820cb254
MAC CLI / 1.0.0
Install the signed Mac CLI.
Download the universal ZIP for Apple silicon and Intel Macs running macOS 14 or later. It contains the signed executable, installer, and CLI guide. Hourfield Mac 1.1.0 build 3 or later must be running for the same user, with Agent access enabled; app beta access is still by invitation.
Paste this into Terminal to download the ZIP and checksum, verify the archive, then run its installer. The installer checks the binary checksum and Developer ID signature. It installs to ~/.local/bin/hourfield and refuses to replace an executable or symlink it does not recognize.
(set -eu
cli_temp="$(mktemp -d)"
trap 'rm -rf "$cli_temp"' EXIT
curl -fL 'https://tieoff.app/apps/hourfield/downloads/hourfield-cli-1.0.0-mac-universal.zip' -o "$cli_temp/hourfield-cli-1.0.0-mac-universal.zip"
curl -fL 'https://tieoff.app/apps/hourfield/downloads/hourfield-cli-1.0.0-mac-universal.zip.sha256' -o "$cli_temp/hourfield-cli-1.0.0-mac-universal.zip.sha256"
cd "$cli_temp"
shasum -a 256 -c 'hourfield-cli-1.0.0-mac-universal.zip.sha256'
unzip -q 'hourfield-cli-1.0.0-mac-universal.zip'
./Hourfield-CLI-1.0.0/install.sh
)For another location, download and extract the ZIP yourself, then run ./install.sh /your/prefix from its folder. Add the chosen bin directory to your PATH. Check hourfield --version and hourfield --json doctor after installing.
Purchases are handled by the Mac app through verified App Store access: $2.99/month with a 14-day introductory trial for eligible new subscribers, or a separate $29.99 one-time lifetime purchase. Creating or editing work requires an active plan; your existing records and reports remain accessible. The CLI cannot purchase or cancel a subscription and does not run a background network server.
ZIP SHA-256 fe11903aa7861df028ae4763fa104ea9e847abde69836c8fc391be5797048196
01 / SETUP
The app stays in control.
Install the signed Mac CLI, then open a compatible Hourfield build on the same Mac and macOS user as your terminal. Turn on Settings → Agents and command line → Allow agent access, and keep the app unlocked while you work. The CLI never writes Hourfield's data file; it asks the running app, which validates and saves each change.
02 / READ FIRST
Check, then act.
Start with read-only commands. Add --json for one stable reply line: {schema:1, ok, data, error, requestID}. Errors carry {code, message, retryable} and exit with 1, or 2 for a typo or unknown command. Money totals are decimal strings, kept separate by currency.
hourfield --json doctorhourfield --json capabilitieshourfield --json timer statushourfield --json jobs list --limit 100 --offset 0doctor reports ready: true only when the app is running, Agent access is on, and the app is unlocked. A locked or disabled app is something to ask the user about, never something to work around.
03 / COMMANDS
Everything the app can do.
Jobs, entries, preferences, and saved views expose every editable field through --patch with camelCase keys. Dates are ISO 8601 with a timezone. Lists return {items, total, limit, offset} and page with --limit (up to 1000) and --offset. Jobs can be selected by UUID or an exact unique name; prefer UUIDs.
Check and discover
hourfield doctorApp heartbeat and readinesshourfield capabilitiesEvery command this install supportshourfield --versionCLI and protocol versionhourfield helpThe full guide for your installed versionhourfield docsPrint the Hourfield website URLJobs
jobs list [--archived true|false] [--query TEXT]Find jobsjobs show IDOne job with its revisionjobs create --name NAME [--rate N --currency USD]Add a jobjobs update ID [--name NAME --rate N --patch JSON]Change any editable fieldjobs archive ID [--archived false]Archive or unarchivejobs copy ID [--name NAME]Duplicate a jobTimers and entries
timer status [--job ID]What is running nowtimer clock-in JOB_IDStart a timertimer break [ENTRY_ID] [--paid true|false]Pause for a breaktimer resume [ENTRY_ID] · timer clock-out [ENTRY_ID]Resume or finishentries list [--job ID --range week]Recorded timeentries show | create | update | copy | deleteManage single entriesReports, files, and organization
reports summary | daily | payperiodTotals, by day, or by pay periodreports print [--range month --timeout 120]Open the Mac Print / Save as PDF panelexport json|csv|xlsx|txt --out NEW_PATHBackup, entries, payroll, or a formatted text reportimport preview FILE · import apply FILE --preview TOKENPreview, then importpreferences get | set --patch JSONCalculation preferencestags … · filters …Rename, merge, and saved viewsApp controls
app status|show|settings|help|lock|unlockDrive the Mac appapp data-folderShow the app's data folder in Finderui navigate SCREEN · ui edit-job ID · ui dismissOpen screens and editorscloud status|enable|disable|syncOptional iCloud pairingbackups list | preview ID | restore ID --preview TOKENSaved versionsnotifications … · location …Permission-backed featurescommand NAME --args-file ARGS.jsonAny command by its raw name04 / SAFE CHANGES
Keep the user's intent attached.
Change jobs, entries, or timers only when the user asked for it. Preview with --dry-run, pass the revision you read with --if-match so a stale update is rejected, and read the record back afterward.
hourfield --json jobs show JOB_IDhourfield --json jobs update JOB_ID --patch '{"rate":85}' --if-match REVISION --dry-runIf someone has an editor or import preview open in the app, record changes wait with editor_busy so their unsaved work is not overwritten. Ask them to finish, or run hourfield ui dismiss only when they have said to.
Requests wait 10 seconds by default. Use --timeout with a whole number from 1 to 120 when a Touch ID or permission prompt needs time, as in hourfield --timeout 120 app unlock. A timeout returns outcome_unknown: check the current state, or repeat the identical command with the original --request-id. Never reuse an ID for a different command.
Imports and backup restores need a preview token, and the token expires if the file or the records change. Exports never overwrite an existing file. reports print and app data-folder open the normal Mac panel or Finder window for the user; nothing is printed or saved silently, and a dry run only describes the action.
05 / DATA & ACCESS
Local by design.
The CLI works only for the current macOS user, through the running app. This website never sees personal records, and iCloud pairing is a separate app feature with no remote command endpoint.
Respect app locking and Agent access. Do not print, upload, or share work history unless the user asked for that exact disclosure.
App locking controls access through the app. It is not file encryption; the Mac account and FileVault protect the files on disk.
Download the signed Mac CLI Download the installable Hourfield skill Machine-readable SKILL.md Every flag and patch field in the full CLI reference Hourfield support How Hourfield handles your data This guide follows the CLI in development.
hourfield help on your Mac is the final word for your version.