CLI Reference

The forg CLI manages your license, sessions, and adapter connections. All commands communicate directly with the FORG engine at https://engine.forg.pro — there is no local agent daemon.

Global flags

forg activate

forg activate <license_key> [flags]

Validates the license key against https://api.forg.pro/agent/v1/activate, stores the identity bundle in the OS keychain, auto-detects installed AI tools, and starts a monitoring session.

forg activate lic_a3f9e2c1b84d7f6e0a2c

# device fingerprint: a3f9e2c1b84d...
# Device name [mymac]:
#   ✓ Claude Code
#   ✓ Cursor
#
# FORG OS activated. 2 tool adapter(s) installed.
# forg: session started (a3f9e2c1)

forg deactivate

forg deactivate [flags]

Ends any active session, removes the identity bundle from the OS keychain, and wipes all local FORG data. The license remains valid on other machines — this only de-registers this device. Requires --confirm to prevent accidental data loss.

forg deactivate
# This will remove your license and delete all local FORG data.
# Run with --confirm to proceed.

forg deactivate --confirm
# forg: deactivated. All local data removed.

forg on

forg on [flags]

Starts a new monitoring session. If a paused session exists, resumes it instead of creating a new one.

forg on
# forg: session started (a3f9e2c1)

# If a paused session exists:
# forg: resuming paused session (a3f9e2c1)

Set or change the session goal explicitly with forg set-goal "...".

forg done

forg done [flags]

Ends the session and requests the end-of-session report from the engine. Clears local session state after the engine acknowledges.

forg pause

forg pause

Suspends interventions without ending the session. The session remains open and can be resumed with forg on or re-anchored with forg refocus.

forg pause
# forg: session paused (a3f9e2c1) — run `forg on` to resume

forg refocus

forg refocus

Resumes a paused session and re-anchors the engine to the declared goal. If the session was not paused, still emits a refocus-ack signal.

forg refocus
# forg: refocused (a3f9e2c1)

forg set-goal

forg set-goal <text...> [flags]

Updates the goal for the active session. All arguments are joined as the goal text.

forg set-goal Refactor the payment module
# goal recorded for session a3f9e2c1

forg status

forg status [flags]

Shows the current state of your activation and active session.

forg status

# user_id:        usr_a3f9e2c1b84d7f6e0a2c
# device:         a3f9e2c1b84d...
# engine:         https://engine.forg.pro
# license worker: https://api.forg.pro
#
# session:        a3f9e2c1 (active)
# goal:           Build the auth flow
#
# Installed adapters:
#   ✓ Claude Code (free)
#   ✓ Cursor (free)

If no session is active:

# session:        none (run 'forg on' to start)

forg connect

forg connect <tool>

Manually installs the adapter for a specific tool. Useful if auto-detection during forg activate missed a tool that was installed later.

forg connect claude-code
# connected: claude-code

forg emit

forg emit [flags]

Emits a lifecycle signal to the engine. This command is invoked automatically by tool adapter hooks — you typically won't run it manually.

When called from a piped context (e.g., a Claude Code hook), stdin is read automatically. There is no --stdin flag; stdin detection is based on whether the process has a TTY.

# Emit a PostToolUse signal (hook reads stdin automatically):
forg emit --event PostToolUse

# Emit with explicit session and tool context:
forg emit --event SessionStart --tool claude-code --session <uuid>

forg update

forg update

Checks for a newer version of the CLI on the FORG release channel. If found, downloads and replaces the binary in-place.

forg update
# forg: checking for updates...
# forg: updated to v3.6.5

forg uninstall

forg uninstall

Removes FORG shell profile hooks and local state. Run manually only when you want a full local uninstall.

forg version

forg version

Prints the CLI version and platform.

forg version
# forg 3.6.5 (darwin/arm64)

Environment variables