Skip to main content

Command-line interface

The timon executable controls agents, missions, tasks and plugins. A source installation exposes it with npm run install:cli in orchestrator/; it can also be called as node orchestrator/bin/timon from a checkout.

Desktop installations​

No separate Node.js installation is needed: the packaged launcher uses Timon's own runtime.

  • Linux deb: the installer adds timon in /usr/bin. The deb is the recommended Linux beta format. Uninstalling removes the link; an existing command from another installation is preserved.
  • Windows: the installer adds its cli directory to the user PATH (or the system PATH for an all-users install). Close and reopen your terminal after installing. Uninstalling removes only that directory from PATH.
  • macOS pkg: the installer adds /usr/local/bin/timon. Install Timon in /Applications; the command follows the app's upgrades. If you later delete the app, remove its CLI symlink too.
  • macOS DMG: drag Timon to /Applications, then run sudo ln -s /Applications/Timon.app/Contents/cli/timon /usr/local/bin/timon once. Create /usr/local/bin with sudo mkdir -p /usr/local/bin if needed. If the link already exists, inspect it before changing it. Ensure /usr/local/bin is on your shell's PATH.
  • AppImage: remains a portable option and does not install a global CLI. Use the deb package when you need terminal commands; do not link into an AppImage's temporary mount directory.

Open Timon and complete first run before issuing daemon commands. timon --help works without a running daemon; timon list requires one. If a command already existed before installation, use the packaged launcher directly to avoid contacting a source installation: /opt/Timon/cli/timon on Linux, /Applications/Timon.app/Contents/cli/timon on macOS, or cli\timon.cmd inside your Windows installation directory.

Inspect first​

timon --help
timon backends
timon list
timon task list
timon plugin list

spawn, task create, plugin installation and other write commands change the instance. wait can block until a mission completes; use its timeout when scripting.

Select the instance​

The CLI automatically finds the local daemon from timon.config.json, then the desktop installation's saved port in desktop-bootstrap.json, under TIMON_HOME (normally ~/.timon). If neither provides a usable address, it falls back to http://localhost:3000.

--daemon selects a URL or named profile and takes precedence over TIMON_API. Without the flag, TIMON_API overrides local discovery. Authentication uses the named profile's token when selected; otherwise it reads TIMON_API_TOKEN or the daemon-token file under the same home. With a raw --daemon URL, the local file token is only used for the local daemon's loopback address, protocol and port. For a remote URL, set TIMON_API_TOKEN explicitly or select a profile created with timon daemon add; otherwise the request is unauthenticated. Use a server-to-server token only in a trusted terminal or process; do not expose it in browser code.

timon --daemon https://your-daemon.example list

Named daemon profiles are also supported. The generated CLI reference documents the source command syntax; avoid assuming that appending --help to every subcommand is harmless, because not every command has a dedicated help handler.

Durable text inputs​

For a task result, write the text to a file and call timon task done TASK_ID --comment-file result.md. This preserves line breaks and avoids shell quoting surprises. Use actual IDs returned by the CLI, not the placeholders used in this guide.

See the generated CLI reference for root help and additional source usage blocks.