Installation CLI

Standalone CLI & Daemon Guide

Use the refact binary for the TUI, daemon control plane, headless run, project registration, logs, events, status checks, and low-level worker debugging.

Refact is installed as one native refact binary. That binary can open the full-screen TUI, start or control the resident daemon, run one-shot headless prompts, manage daemon projects, update itself, and expose the lower-level worker engine for developers.

Mental model

• refact / refact tui is the normal user entrypoint. Running refact with no subcommand opens the full-screen TUI. refact tui --project . does the same thing while choosing the project explicitly.
• refact daemon is the resident local control plane. Normal TUI and management commands auto-start it when needed. refact daemon --foreground is mainly for debugging or service supervision.
• Project workers are the per-project backend engines. The daemon keeps one warm worker per opened project. A worker owns the HTTP/SSE chat API, LSP, tools, project indexes, memory, tasks, checkpoints, and provider calls for that project.
• Clients attach to daemon-managed projects. The TUI, browser GUI, VS Code, and JetBrains clients all talk to the same daemon and project workers instead of booting separate engines for each UI.
• Direct worker mode is for developers. refact worker ... runs the engine directly and bypasses the daemon project registry; use it for low-level engine debugging, not everyday chat.

Install and first run

Unix / macOS:

curl -fsSL https://raw.githubusercontent.com/JegernOUTT/refact/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/JegernOUTT/refact/main/install.ps1 | iex

The installer detects your OS/architecture, downloads the matching binary from GitHub Releases, verifies its checksum, installs it to ~/.refact/bin/refact, and adds that directory to your PATH where possible.

From a project directory, start with:

refact projects open .
refact

refact projects open . registers the current directory with the daemon and starts or reuses its worker. refact opens the interactive TUI and starts or reuses the same daemon.

Configure at least one model source next: a hosted BYOK provider key/OAuth flow, a local runtime such as Ollama/LM Studio/vLLM, or a custom OpenAI-compatible endpoint. See BYOK and Supported Models.

Everyday workflows

Open or register a project

cd /path/to/project
refact projects open .
refact projects

Useful registry commands:

refact projects pin .
refact projects unpin .
refact projects forget .

Targets can be a registered project path or a unique project id prefix from refact projects / refact ps.

Start the TUI

refact
refact tui --project .

Use bare refact for the current directory. Use refact tui --project <path> when launching from somewhere else.

Run a one-shot headless prompt

refact run --project . --json "Summarize this repository and list the safest first task."
refact run --project . --mode explore "Explain how scheduler jobs are loaded."
refact run --project . --approve ask "Update the docs for the new command."

refact run sends one prompt through the daemon-managed project worker. Defaults are agent mode, --approve deny, text streaming, and a 600 second timeout. Use --json for machine-readable output. Use --approve ask for interactive approvals or --approve auto only in a trusted workspace.

Inspect daemon and project health

refact status
refact ps
refact logs --daemon -f
refact logs . -f
refact events -f
refact doctor

• status checks daemon reachability without spawning a worker.
• ps lists the daemon and registered workers.
• logs --daemon -f follows daemon logs.
• logs . -f follows the current project's worker log.
• events -f follows daemon event stream records.
• doctor checks daemon metadata, ports, versions, worker responsiveness, project roots, and lock files.

All daemon management commands support --json, except JSON output is intentionally incompatible with follow mode (-f / --follow).

Restart or stop things

refact restart .
refact stop .
refact restart --daemon
refact stop --daemon

Project restart/stop targets a registered project path or id prefix. Daemon restart/stop targets the control plane itself.

Update the binary

refact self-update
refact self-update --check
refact self-update --version 8.2.0

self-update downloads the matching release asset, verifies its checksum, and atomically replaces the current binary. --check reports current/latest versions without installing.

Command reference

Command	Use it for	Example
refact	Open the full-screen TUI for the current project and auto-start the daemon.	refact
refact tui --project .	Open the TUI for an explicit project path.	refact tui --project .
refact daemon --foreground	Run the daemon in the foreground for logs, debugging, or a process supervisor.	refact daemon --foreground
refact run	Run one headless chat turn through the daemon.	refact run --project . --json "Explain this repo"
refact projects open .	Register/open a project and start or reuse its worker.	refact projects open .
refact ps	List daemon workers.	refact ps
refact status	Print daemon health.	refact status
refact logs --daemon -f	Follow daemon logs.	refact logs --daemon -f
refact logs . -f	Follow the current project worker log.	refact logs . -f
refact events -f	Follow daemon events.	refact events -f
refact doctor	Diagnose daemon setup.	refact doctor
refact restart --daemon	Restart the daemon.	refact restart --daemon
refact stop --daemon	Stop the daemon.	refact stop --daemon
refact self-update	Update the installed binary from GitHub Releases.	refact self-update

Additional useful forms:

refact projects --json
refact ps --json
refact status --json
refact events --kind worker_ready
refact logs <project-id-prefix>
refact restart <project-id-prefix>
refact stop <project-id-prefix>
refact version

When to use refact worker directly

Use direct worker mode mainly if you are developing or debugging the Rust engine itself. Normal users should prefer refact, refact tui, refact run, and the daemon project commands because those keep the project registry, shared clients, logs, and lifecycle management in one place.

Installed binary example:

cd /path/to/project
refact worker --http-port 8001 --workspace-folder "$PWD" --ast --vecdb --logs-stderr

From a source checkout, you can also run the legacy engine binary directly:

cd refact-agent/engine
cargo run --bin refact-lsp -- --http-port 8001 --workspace-folder /path/to/project --ast --vecdb --logs-stderr

Direct worker/engine runs expose the project HTTP API at the selected port and can also run LSP, AST, and VecDB services. They do not replace the daemon-managed user flow.

Troubleshooting

• The old --tui flag form is invalid. Use refact or refact tui.
• Things look weird or stale: run refact status, then refact logs --daemon -f, then refact doctor.
• The TUI cannot attach to a project: run refact projects open ., then refact ps to confirm the worker exists.
• A project worker is stuck: run refact logs . -f; if needed, refact restart ..
• The daemon is stuck or version-mismatched: run refact restart --daemon; if that fails, inspect refact doctor and refact daemon --foreground.
• Headless automation needs stable output: use refact run --json ... and check the returned error kind/exit code.

Related pages

• Quickstart
• Installation Overview
• Architecture
• BYOK
• Agent Modes
• Processes & PTY