TERMINAL INTEGRATION

CLI automation for terminal commands.

The bundled `goblin` command-line tool starts a Token Goblin run, executes a terminal command, records pass or failure, and returns the child command’s original exit status. Manual tracking remains available for any task; the CLI is specifically for terminal automation.

Download free for MacSee Token Goblin

AT A GLANCE

  • Commands: start, finish, run, show
  • Uses local app IPC
  • Passes through terminal I/O
  • Preserves wrapped command exit status
  • Does not parse code or command output

Seven-day full access. One-time lifetime unlock. Apple shows the current localized price in the Mac App Store.

Wrap a command

Use `goblin run` when a terminal command should define the run’s start and finish. The CLI forwards the child process’s standard input, standard output, and standard error to your terminal, then sends a success result when the command exits with status 0 or a failure result otherwise.

Explicit start and finish

Use `goblin start` and `goblin finish` when another tool or script knows the task boundaries. `goblin show` asks the app to come forward. The app must be installed and launched at least once so macOS can register the bundle and URL integration.

Failure behavior and limitations

If the app cannot be contacted, a command is rejected, or acknowledgement times out, the CLI writes an error to stderr and exits with status 2. A wrapped child command’s own exit status is preserved after Token Goblin records the result.

The CLI does not inspect command output or infer files changed and tests broken. Those result fields are explicit inputs for `finish`; a wrapped `run` currently reports a failed child as one broken test and does not discover file counts.

Common command shapes

goblin start --title "Run unit tests" --agent Terminal --expected 5
goblin finish --success --files 8 --tests-broken 0
goblin run --title "Build the app" --expected 10 -- swift build
goblin show

Common questions

Can I track any task manually?

Yes. Token Goblin supports manual tracking for any task, plus CLI automation for terminal commands. Choose a runner label such as Codex, Claude, Xcode, Terminal, or Custom.

Does Token Goblin read my code, prompts, or terminal output?

No. Token Goblin does not read prompts, source code, repository contents, terminal output, or file paths. The CLI sends only the task details and result metrics you explicitly provide.

What happens if the CLI cannot contact the app?

The CLI reports the problem on stderr and exits with status 2. A wrapped child command’s own exit status is preserved after a successful Token Goblin handoff.