Command line & git difftool¶

OctoEdit has a small, script-friendly command-line surface: open files (with an optional caret position), tweak a run with a few options, and — the headline — act as a fast two-file compare viewer for git difftool.

OctoEdit [options] [files...]

Paths may be relative or absolute. When launched from a console, --help/--version print there; started any other way, they appear in a small dialog instead.

Opening files¶

OctoEdit notes.txt src\main.cpp README.md

Each file opens in its own tab. A path that does not exist yet opens as a new, unsaved buffer bound to that name (saving creates the file).
A trailing :line or :line:column on the first file moves the caret (1-based, clamped to the document) — handy from compilers and grep output:

OctoEdit src\main.cpp:120:8

With single instance enabled (the default), a second launch forwards its files to the running window and exits.

Options¶

Option	Meaning
`-h`, `--help`	Print usage and exit.
`-v`, `--version`	Print the application version and exit.
`--log <level>`	Minimum log level for this run: `trace`, `debug`, `info`, `warning` or `error`.
`--rendering <mode>`	How this run composes its windows: `gpu` (the default) or `cpu`. Applies to that run only (see below).
`--list-debug-flags`	List the recognised debug flags with their current values and exit.
`--diff <left> <right>`	Compare two files in a transient read-only viewer (implies `--viewer`).
`--viewer`	Transient read-only viewer instance (see below).
`--readonly`	Open the listed files read-only (see below).

`--rendering`: window composition for one run¶

OctoEdit --rendering=cpu

Chooses how this run composes its windows — gpu (the default) or cpu — and nothing else. See Preferences ▸ General ▸ Window rendering for what the two modes mean.

It applies to that run only and is never saved: the next plain launch is back to whatever Preferences says.
The mode is decided before the first window exists and cannot change while the editor runs, so it covers the editor window and a --viewer / --diff window alike. An unknown mode is reported and ignored.
With single instance on (the default), a launch that is forwarded to a running editor only hands over its files — the running window keeps the mode it started with, so --rendering changes nothing there.

If the editor window cannot be used after start-up

If the window comes up drawn wrongly, or does not appear at all, start the editor once with --rendering=cpu and then set Preferences ▸ General ▸ Window rendering to CPU yourself — the command-line option is not remembered, so it gets you in, and the preference makes it stick.

If you cannot get that far either, the setting can be edited by hand while the editor is closed. Add to the [app] section of the configuration file:

[app]
rendering\mode=cpu

The file is at:

Windows: %APPDATA%\7-bits\OctoEdit.ini
macOS: ~/.config/7-bits.eu/OctoEdit.ini
Linux: ~/.config/7-bits/OctoEdit.conf

`--readonly`: open specific files locked¶

OctoEdit --readonly production.conf notes.txt

Opens the listed files with editing disabled — the modifying commands (Cut, Paste, Undo…) grey out for those tabs while Copy keeps working. Unlike --viewer, this is a normal editor instance: your session restores, you can open and edit any other document, and a second --readonly launch forwards its files into the running window locked as well. Two guard rails: a listed file that is already open with unsaved changes stays editable (the flag never traps changes you could no longer save), and a listed path that does not exist yet opens as a locked empty buffer.

`--diff`: a two-file compare window¶

OctoEdit --diff old.txt new.txt

Opens a separate, throwaway window whose only tab is the side-by-side comparison of the two files — syntax-coloured, read-only, with the full compare toolset: difference navigation, the overview ruler, ignore-whitespace/case and Aligned toggles, and copy-change merging with per-side save (both operands are real files, so both directions work).

Exactly two existing files are required. A missing file or a directory is reported and the process exits with code 2 without opening an editor window (directory comparison lives in the Folder Compare plugin).
The process stays alive until you close the window, then exits 0 — which is exactly what git difftool waits for.
The window is independent of your normal OctoEdit: it never joins the single-instance mechanism, loads no plugins, and saves nothing (no session, no layout, no recent-files entries). Your editor and its session are untouched, and any number of --diff windows can coexist with it.
The AI assistant stays available — it is part of the core. Asking a question there automatically tells the agent which two files are on screen (and grants it read access to both), so "what changed between these files?" just works.

Set it up as your git difftool¶

# .gitconfig
[diff]
    tool = octoedit
[difftool]
    prompt = false
[difftool "octoedit"]
    cmd = OctoEdit --diff "$LOCAL" "$REMOTE"

Then, for example:

git difftool HEAD~1 -- src/main.cpp

Tip

Make sure OctoEdit.exe is on your PATH, or write its full path into the cmd = line.

`--viewer`: a throwaway read-only viewer¶

OctoEdit --viewer report.log

A transient instance for a quick look at a file, without disturbing your real editing session (implied by --diff):

The files given on the command line open normally — then the instance is locked: the buffers are read-only, File ▸ New/Open/Save and all Compare commands are disabled, and nothing can open another tab.
Closing the last tab closes the window.
Nothing persists: no session save or restore, no window-layout writes, no recent-files entries.
No plugins load, so it starts fast; core features — syntax colouring, themes, the AI assistant — remain available.

Exit codes¶

Code	Meaning
`0`	Normal exit, including a closed `--diff`/`--viewer` window.
`2`	Invalid `--diff` request (wrong operand count, missing file, directory operand).