The rfc command line

rfcis the RefocusedEngine command-line client. It starts and stops the engine, submits and cancels jobs, monitors progress, builds hardware-optimized inference engines, and manages configuration. It talks to a running engine over the engine's local HTTP command API (default localhost:8080).

rfc [OPTIONS]                    # interactive mode (full-screen UI)
rfc [OPTIONS] COMMAND [ARGS...]  # run one command and exit

Everything the desktop app does with jobs, the CLI can do headless — the app andrfc are both clients of the same engine.

rfc ships two ways:

Inside the Refocused app

The CLI is bundled at Refocused.app/Contents/Resources/bin/rfc. To put rfc on your PATH, run once:

/Applications/Refocused.app/Contents/Resources/scripts/install_cli.sh

CLI-only bundle

A standalone bundle (RefocusedCLI-<version>-macos_arm64.tar.gz, no GUI) is available for headless machines. Extract it anywhere and run ./install_cli.sh from the extracted directory.

Both create a symlink at /usr/local/bin/rfc and, if missing, the default engine configuration at ~/Documents/RefocusedApp/configs/app_config.json.

# license this machine (no account required)
rfc redeem RF-XXXX-XXXX-XXXX

# start the engine in the background
rfc start

# submit a job file (see "Job files" below)
rfc add my_job.json

# watch progress in the full-screen UI
rfc

# stop everything when done
rfc shutdown

Run rfc with no command for the interactive full-screen UI — a command bar plus Output, History, and Help tabs. All commands work in the command bar; arrow keys recall history, Tab moves between UI elements, and exit leaves the UI while the engine keeps running.

Engine lifecycle

Jobs

Engine optimization

Optimization builds inference engines tuned for your local hardware. Builds run asynchronously on the engine and are polled with status:

rfc optimize <type> [key=value ...]   # start a build
rfc optimize <type> status            # show the running build's status
rfc optimize <type> cancel            # cancel the running build

Build parameters are passed as key=value pairs (tile sizes, variant, force_overwrite, ...). The trt_* types additionally accept opt_level=<0–5> (TensorRT builder optimization level, default 3) and compatible=true for hardware-portable engines. The engine runs one build at a time.

rfc optimize cml_segment variant=tiny
rfc optimize cml_regenerate_q tile=768 kv_len=3
rfc optimize cml_dynamic tiles="270,480;540,960"
rfc optimize cml_depth_est variant=relative size=small
rfc optimize trt_denoise tile_h=512 tile_w=768 opt_level=1

Engine refresh

Device & licensing

Configuration

rfc set <key> <value> writes CLI settings to the CLI config file, and anything else — including dot-notation keys — to the engine configuration file (see Engine configuration):

rfc set job_history_length 5
rfc set output.enable_history_logging true

A job file is a JSON array of job objects. A file with one entry runs one job; multiple entries run in order, which is how batches and multi-stage pipelines are expressed. Only three fields are required — id, input_path, and output_path; everything else has sensible defaults.

[
  {
    "id": "beach_refocus_4x",
    "input_path": "footage/beach_1080.mp4",
    "output_path": "output/beach_8k.mp4",
    "model_type": "refocus",
    "encoder": {
      "vcodec": "hevc_videotoolbox",
      "pix_format": "p010le",
      "container": "mp4"
    }
  }
]

Top-level fields

scaling

encoder

All fields optional; values are FFmpeg names, so any string your media libraries support is accepted. Which encoders are available depends on the platform — hardware H.264/H.265 via VideoToolbox (macOS) or NVENC (NVIDIA) always ship; software x264/x265 require your own FFmpeg build.

image_output

Per-model blocks

On macOS, each model's coreml block selects compute units: CPU_AND_GPU (default), CPU_AND_NE (Neural Engine), or ALL (run GPU and Neural Engine concurrently where supported).

Example: two-stage pipeline (Refocus → Regenerate-Q)

[
  {
    "id": "clip_stage_1",
    "input_path": "footage/clip_270p.mp4",
    "output_path": "output/clip_stage_1.mp4",
    "model_type": "refocus",
    "refocus": { "coreml": { "coreml_compute_type": "ALL" } }
  },
  {
    "id": "clip_stage_2",
    "input_path": "output/clip_stage_1.mp4",
    "output_path": "output/clip_final.mp4",
    "model_type": "regenerate_q",
    "scaling": { "upscale_factor": 1 },
    "regenerate": {
      "minimum_tile_overlap_h": 128,
      "minimum_tile_overlap_w": 128,
      "coreml": { "concurrent": true }
    }
  }
]

Example: metric depth maps as a 16-bit image sequence

[
  {
    "id": "clip_depth",
    "input_path": "footage/clip.mp4",
    "output_path": "output/depth/",
    "model_type": "depth_est",
    "depth_variant": "metric",
    "depth_size": "base",
    "output_mode": "image_sequence",
    "image_output": {
      "format": "png",
      "bit_depth": 16,
      "color_mode": "grayscale"
    }
  }
]

The engine reads a single JSON configuration file, used by rfc start and rfc optimize. Installed location: ~/Documents/RefocusedApp/configs/app_config.json. Every key is optional — missing keys take the defaults below. Edit it directly or with rfc set <dotted.key> <value>, then apply with rfc refresh config or an engine restart.

{
  "engines_location": "models/release",
  "weights_location": "weights",
  "log_level": "WARNING",
  "license_file_location": "license/license.rflic",
  "engines": { "load_on_startup": [] },
  "inference_manager": { "max_engines": 2 },
  "pipeline": { "max_active_processing_units": 24 },
  "command_interface": { "enabled": true },
  "monitoring": {
    "enabled": true,
    "status_server": { "tcp_port": 8080, "bind_address": "127.0.0.1" }
  },
  "output": { "enable_history_logging": true }
}

Top level

engines

inference_manager & pipeline

command_interface & monitoring

output

File locations

Troubleshooting