CLI tool
The freeact or freeact run command starts the interactive mode:
freeact
A .freeact/ configuration directory is created automatically if it does not exist yet. The init subcommand initializes the configuration directory without starting the interactive mode:
freeact init
Options
| Option | Description |
|---|---|
--sandbox |
Run code execution in sandbox mode. |
--sandbox-config PATH |
Path to sandbox configuration file. |
--log-level LEVEL |
Set logging level: debug, info (default), warning, error, critical. |
--record |
Record the conversation as SVG and HTML files. |
--record-dir PATH |
Output directory for recordings (default: output). |
--record-title TEXT |
Title for the recording (default: Conversation). |
Examples
Running code execution in sandbox mode:
freeact --sandbox
Running with a custom sandbox configuration:
freeact --sandbox --sandbox-config sandbox-config.json
Recording a session for documentation:
freeact --record --record-dir docs/recordings/demo --record-title "Demo Session"
Interactive Mode
The interactive mode provides a conversation interface with the agent in a terminal window.
User messages
| Key | Action |
|---|---|
Enter |
Send message |
Option+Enter (macOS)Alt+Enter (Linux/Windows) |
Insert newline |
q + Enter |
Quit |
Image Attachments
Reference images using @path syntax:
@screenshot.png What does this show?
@images/ Describe these images
- Single file:
@path/to/image.png - Directory:
@path/to/dir/includes all images in directory, non-recursive - Supported formats: PNG, JPG, JPEG, GIF, WEBP
- Tab completion available for paths
Images are automatically downscaled if larger than 1024 pixels in either dimension.
Approval Prompt
Before executing code actions or tool calls, the agent requests approval:
Approve? [Y/n/a/s]:
| Response | Effect |
|---|---|
Y or Enter |
Approve once |
n |
Reject once (ends the current agent turn) |
a |
Approve always (persists to .freeact/permissions.json) |
s |
Approve for current session |
See Permissions API for details.