make your
point.

getting started

Choose the installer or portable download for Windows 11. Run greenflame.exe; it stays in the system tray, ready when you need it. You can take your first screenshot without editing any settings.

your first capture

capture & selection

greenflame uses a capture-first model. When you trigger an interactive capture, greenflame freezes the desktop into a snapshot. You then select a region from that frozen image, not from a live view that shifts as you draw.

Your desktop selection stays still while you work. Window selection can capture the chosen window separately, including portions outside the visible desktop.

selection modes

Four ways to define what gets captured:

• Click and drag: draw a freehand rectangle. Hold Alt to disable edge snapping.
• Ctrl + click: select the window under the cursor. While Ctrl is held, greenflame lifts the window preview above any occluding windows. If the window extends off-screen, the full window is still captured, but only the on-desktop portion is editable; a note beneath the center size label indicates that off-screen pixels are included.
• Shift + click: select the entire monitor under the cursor.
• Shift+Ctrl + click: select the full virtual desktop (all monitors).

adjusting the selection

Once a region is selected, you can refine it before annotating or saving:

• Drag the handles on the selection border to resize it. Hold Alt to disable snapping.
• With no annotation tool active (the default), drag inside the selection to move it. Hold Alt to disable snapping.
• Press Ctrl+K or use the toolbar button to show or hide the captured cursor, meaning the cursor as it appeared in the frozen screenshot. This affects the saved image, not the live editing pointer.
• Press Ctrl+P or use the toolbar button to pin the current selection as a floating reference window.

moving annotations

With no annotation tool active, you can manipulate existing annotations:

• Click and drag an annotation to select it, then drag inside its bounding box to move it.
• Ctrl+click an annotation to add or remove it from the current multi-selection.
• Ctrl+drag a marquee to add every touched annotation to the selection.
• When multiple annotations are selected, drag inside the group bounding box to move them all.
• A selected line or arrow shows draggable endpoint handles for reshaping.
• A selected rectangle, ellipse, or obfuscate (exactly one) shows corner and side resize handles.

annotation tools

greenflame has 11 tools. Press a hotkey or click the toolbar to toggle a tool on. Pressing the same hotkey again deactivates it and returns to selection mode.

color, size & cursor previews

Color: With any tool other than Obfuscate active, right-click anywhere (or press Tab) to open the color selection wheel. Left-click a segment or press Enter to select it. Scroll the mouse wheel or press ↑/↓ to navigate segments without the mouse. Press Escape to dismiss without changing. For Text and Bubble, the wheel has a central hub that switches between 8 color slots and 4 font choices; pressing Tab while the wheel is open cycles between color and font views.

Size: With any sized tool active (Brush, Highlighter, Line, Arrow, Rectangle, Ellipse, Bubble, Obfuscate, or Text), use mouse-wheel up/down or Ctrl+= / Ctrl+− to change that tool's size step (1–50). Each tool remembers its own independent size setting. For Obfuscate, the size controls block_size: 1 = blur mode, 2..50 = block pixelation.

Cursor previews: Most tools show a live preview around the cursor to indicate the current stroke size:

• Brush and Bubble: anti-aliased circular preview.
• Highlighter, Line, Rectangle, Ellipse, and Obfuscate: anti-aliased axis-aligned square preview.
• Arrow: square preview aligned to the current arrow direction.
• Text: the letter "A" in the current font and size, beside the cursor.
• Filled Rectangle and Filled Ellipse: no cursor preview.

text

With the Text tool active and no draft open, left-click inside the selection to start a text annotation. Right-click or press Tab to open the color/font wheel. Use mouse-wheel or Ctrl+=/Ctrl+− to change the text size step (1–50, mapped to 5–288 pt).

Clicking outside a draft commits it if it contains text, or discards it if empty. Committed text annotations can be selected, moved, and deleted, and re-edited. With no annotation tool active, select exactly one text annotation and double-click it to resume editing.

Spell check: Live squiggles appear under misspelled words during editing. Configure one or more BCP-47 language tags in tools.text.spell_check_languages (e.g. ["en-US", "fr-CA"]). When multiple languages are configured, a word is only flagged if all checkers agree it is misspelled. Squiggles never appear in saved images.

While editing a draft:

bubble

Left-click inside the selection to place a numbered circle. The number auto-increments with each placement and decrements on undo. Right-click opens a style wheel; the central hub switches between 8 color slots and 4 font choices. The number color (black or white) is chosen automatically for best contrast against the fill.

highlighter

Draw a semi-transparent stroke to emphasize content. While drawing, holding the mouse still for 800 ms snaps the stroke to a straight bar from the start point to the cursor. After snapping, the bar tracks the mouse until you release. The snap is one-way and cannot revert to freehand.

The wait time is configurable via tools.highlighter.pause_straighten_ms. Setting it to 0 makes every stroke start as a straight bar immediately.

obfuscate

Drag out a rectangle to blur or pixelate the content underneath. block_size = 1 uses blur mode; values 2..50 use block pixelation. Obfuscated regions can be moved and resized after placement, and they recompute automatically when overlapping annotations below them change.

The first time you activate Obfuscate (from the toolbar or by pressing O), greenflame shows a warning dialog with this message. You must click I Understand to proceed. The acknowledgement is saved to tools.obfuscate.risk_acknowledged in the config and the warning does not appear again.

saving & sharing

Save As supports PNG, JPEG, and BMP. When the captured cursor is visible (toggled with Ctrl+K or the toolbar button), it is composited into the screenshot below all annotations. The cursor is never selectable or movable.

pinned images

Pinned images are frameless, always-on-top reference windows with an always-visible green halo. The halo brightens when the pin is focused. Multiple pins can coexist on screen.

• Drag anywhere on the pin to reposition it.
• Use the mouse wheel or Ctrl+= / Ctrl+− to zoom (25%–800%).
• Right-click the pin for its context menu.
• Copy and save actions include the current rotation, but on-screen opacity and the green halo are display-only; they are not baked into exported images.

command line

Use the command line to capture and save without opening the selection overlay. Target a window by title, a monitor by number, a region by coordinates, or the full desktop. Add padding and annotations from JSON, or annotate an existing image.

The examples below use Windows Command Prompt (cmd.exe) with greenflame.exe available in the current folder or on PATH. Use a JSON file to avoid shell-specific quoting when working in PowerShell.

With no arguments, greenflame starts normally in the tray. Pass any of the flags below for a one-shot capture that writes output and exits.

capture modes

At most one capture mode per invocation:

output options

These optional flags modify a capture:

Both --option=value and --option value forms are accepted.

--cursor and --no-cursor override the persisted capture.include_cursor config setting for one invocation only. They do not modify the config file.

padding

--padding accepts one value (n), two values (h,v), or four values (l,t,r,b). Padding is always synthetic color; it never captures extra screen pixels. When padding is present, any part of the capture area that lies outside the virtual desktop is filled with the resolved padding color instead of being clipped.

Padding color resolution:

1. --padding-color, if provided on the command line.
2. save.padding_color from the config file.
3. Default black (#000000).

greenflame.exe --desktop --padding 12
greenflame.exe --monitor 2 --padding 24,12 --padding-color "#ffffff"
greenflame.exe --region 1200,100,800,600 --padding 8,16,24,32

window matching

--window <name> performs a case-insensitive substring search across visible top-level windows. If that search finds exactly one case-insensitive exact-title match, greenflame captures it automatically. If multiple windows remain ambiguous, error output lists each candidate with its HWND, window class, and rect so you can rerun with --window-hwnd.

greenflame.exe --window "Notepad" --output note.png
greenflame.exe --window-hwnd 0x0000000000123456 --output exact-window.png

capture backends

--window-capture is a CLI-only option that controls how window pixels are obtained. It applies only to --window and --window-hwnd.

The key difference: GDI captures what is visible on the desktop, so obscured or off-screen portions may be missing. WGC captures the window itself, even when another window is in front of it or it extends beyond the desktop. Minimized windows are rejected in all modes (exit code 13).

greenflame.exe --window "Notepad" --window-capture gdi --output note-gdi.png
greenflame.exe --window "Notepad" --window-capture wgc --output note-wgc.png

output format

greenflame resolves the output image format in this order:

1. If --output has a supported extension (.png, .jpg, .jpeg, .bmp), that extension defines the format.
2. If --format is provided, it defines the format.
3. With --input, an extensionless --output preserves the probed input format.
4. Otherwise, save.default_save_format from the config applies.

If --output extension conflicts with --format, or the extension is unsupported (e.g. .tiff), the command fails. If --output has no extension, greenflame appends one based on the resolved format.

CLI annotations

greenflame's CLI can apply annotations directly to captured or imported images using a JSON description. This turns the command line into a scriptable annotation engine, useful for build pipelines, automated documentation, and AI agent workflows.

rem Inline JSON
greenflame.exe --desktop --annotate "{\"annotations\":[{\"type\":\"arrow\",\"start\":{\"x\":20,\"y\":20},\"end\":{\"x\":200,\"y\":120},\"size\":4,\"color\":\"#ff0000\"}]}"

rem JSON file
greenflame.exe --region 100,100,400,300 --annotate marks.json --output result.png

rem Annotate an existing image and save a new copy
greenflame.exe --input screenshot.png --output annotated.png --annotate annotations.json

input rules

• --annotate is valid with any capture mode (--region, --window, --monitor, --desktop) or with --input.
• --input requires --annotate. It also requires either --output or --overwrite.
• --input is incompatible with live capture modes and with --window-capture, --cursor, and --no-cursor.
• If the value's first non-whitespace character is {, it is treated as inline JSON. Otherwise, it is treated as a file path.
• Annotation files must be UTF-8 JSON. A UTF-8 BOM is accepted.
• Imported images must be fully opaque. Any non-opaque alpha fails with exit code 16.

schema structure & coordinate spaces

Annotation input is a JSON object with this shape:

{
  "coordinate_space": "local",
  "color": "#ff0000",
  "highlighter_opacity_percent": 50,
  "font": { "preset": "sans" },
  "annotations": [
    { "type": "arrow", "start": {"x": 20, "y": 20}, "end": {"x": 200, "y": 120}, "size": 4 }
  ]
}

Top-level fields:

coordinate spaces

All coordinates are integer physical pixels.

• local: (0, 0) is the top-left of the captured region or the imported image. This is the default and works with all sources.
• global: (0, 0) is the top-left of the virtual desktop. Valid only for live capture modes. Using "global" with --input fails with exit code 14.

Coordinates can be negative or exceed the capture bounds; annotations are not clipped to the source image. When --padding is used, annotations that extend outside the capture area are rendered over the synthetic padding.

defaults and overrides

Values resolve in this order:

1. Annotation-level value (if present on the individual annotation)
2. Document-level value (top-level field in the JSON)
3. greenflame config default (from greenflame.json)

This applies to color, highlighter opacity, and font. Size resolves from the annotation to that tool’s configured default; there is no document-level size field.

annotation types

11 annotation types are available, matching the GUI tools:

lines and arrows

Both use start and end as {"x": int, "y": int} points, plus an optional size for stroke width.

{
  "type": "arrow",
  "start": { "x": 50, "y": 30 },
  "end": { "x": 250, "y": 150 },
  "size": 4,
  "color": "#ff3b30"
}

rectangles and ellipses

Outlined variants accept an optional size for stroke width; when omitted, the tool’s configured size is used. Filled variants do not accept size. Rectangles use left, top, width, height. Ellipses use center, width, height.

{
  "type": "rectangle",
  "left": 10, "top": 10, "width": 200, "height": 120,
  "size": 3, "color": "#00c2ff"
}

{
  "type": "filled_ellipse",
  "center": { "x": 120, "y": 80 },
  "width": 100, "height": 60,
  "color": "#83dd00"
}

brush and highlighter

Both accept a points array of {"x": int, "y": int} objects. Brush uses the shared freehand smoothing controlled by tools.brush.smoothing_mode. Point-list Highlighter uses the same smoothing controlled by tools.highlighter.smoothing_mode.

Highlighter also supports a straight-bar form using start/end instead of points. Straight bars bypass freehand smoothing and keep their explicit geometry.

{
  "type": "highlighter",
  "start": { "x": 10, "y": 50 },
  "end": { "x": 300, "y": 50 },
  "size": 14,
  "color": "#ffe66d",
  "opacity_percent": 40
}

obfuscate

Uses rectangle coordinates. size controls the obfuscation mode: 1 = blur, 2..50 = block pixelation. Does not accept color, font, or highlighter opacity.

{
  "type": "obfuscate",
  "left": 80, "top": 30, "width": 150, "height": 40,
  "size": 8
}

bubble

Numbered circles placed at center. Numbers are assigned automatically by order in the array: first bubble is 1, second is 2, and so on.

{
  "type": "bubble",
  "center": { "x": 40, "y": 40 },
  "size": 12,
  "color": "#ff7a00",
  "font": { "preset": "sans" }
}

text & fonts

Text annotations support either plain text or rich text with per-span formatting.

plain text

{
  "type": "text",
  "origin": { "x": 20, "y": 20 },
  "size": 18,
  "text": "Hello\nworld"
}

rich text (spans)

Use the spans array for mixed formatting. Each span requires a text string and can toggle bold, italic, underline, and strikethrough. Spans cannot override color, font, or size; those are set at the annotation level.

{
  "type": "text",
  "origin": { "x": 20, "y": 20 },
  "size": 18,
  "color": "#ff00ff",
  "spans": [
    { "text": "Step 1", "bold": true },
    { "text": "\nCollect logs", "underline": true },
    { "text": "\nConfirm repro", "italic": true }
  ]
}

fonts

Fonts use a tagged union: either a preset name or an explicit installed family:

// Preset (resolves via config)
{ "preset": "mono" }

// Explicit installed font
{ "family": "Consolas" }

Available presets: sans, serif, mono, art. These resolve to the font families configured in tools.font.* (Arial, Times New Roman, Courier New, and Comic Sans MS by default).

If an explicit family is not installed on the system, the command fails with exit code 14.

colors, transparency & size

• Colors use #rrggbb format. Alpha is not encoded in the color string.
• Highlighter transparency uses opacity_percent on an annotation, or highlighter_opacity_percent for the document default (0–100).
• size uses the same 1–50 step concept as the GUI.

What size controls per type:

validation & rendering

validation

Validation is strict. greenflame does not partially apply a document. If any part of the annotation payload is invalid, the entire command fails with exit code 14.

• Unknown properties are errors.
• Invalid property combinations are errors.
• Wrong types are errors.
• Missing required fields are errors.
• Malformed JSON is an error.

rendering order

For CLI renders, greenflame builds the output image in this order:

1. Source image pixels.
2. Synthetic fill for off-desktop regions (live captures only).
3. Outer padding (when --padding is used).
4. Annotations, in array order.

Annotations always appear on top of the final image, including any padded area. Obfuscate annotations affect the pixels beneath them and earlier annotations, and they recompute when overlapping annotations below them change.

complete example

A full annotation file that uses multiple types, document-level defaults, and per-annotation overrides:

{
  "coordinate_space": "local",
  "color": "#ff3b30",
  "highlighter_opacity_percent": 35,
  "font": { "preset": "mono" },
  "annotations": [
    {
      "type": "rectangle",
      "left": -18, "top": -12, "width": 170, "height": 90,
      "size": 3
    },
    {
      "type": "highlighter",
      "points": [
        {"x": -12, "y": 28}, {"x": 48, "y": 32},
        {"x": 132, "y": 30}, {"x": 188, "y": 36}
      ],
      "size": 11, "color": "#ffe66d"
    },
    {
      "type": "arrow",
      "start": {"x": 168, "y": 84}, "end": {"x": 24, "y": 22},
      "size": 5, "color": "#00c2ff"
    },
    {
      "type": "text",
      "origin": {"x": 12, "y": 96},
      "size": 20, "color": "#ff00ff",
      "spans": [
        {"text": "Step 1", "bold": true},
        {"text": "\nCollect\tlogs", "underline": true},
        {"text": "\nConfirm repro", "italic": true}
      ]
    },
    {
      "type": "bubble",
      "center": {"x": 8, "y": 8},
      "size": 12
    },
    {
      "type": "line",
      "start": {"x": -20, "y": 150}, "end": {"x": 220, "y": 150},
      "size": 2, "color": "#7fff00"
    },
    {
      "type": "bubble",
      "center": {"x": 196, "y": 146},
      "size": 14, "font": {"preset": "sans"}, "color": "#ff7a00"
    }
  ]
}

In this example, the rectangle inherits the document-level "#ff3b30" color, while the arrow and highlighter override it with their own. The first bubble inherits the document-level "mono" font, while the second overrides it with "sans". Negative coordinates on the rectangle and line extend the annotations beyond the top-left of the capture area.

exit codes

Non-zero codes are unique and never reused. Scripts can rely on specific codes to diagnose failures.

keyboard reference

All shortcuts in one place.

system hotkeys

These use the Print Screen key with modifier combinations. They are also available from the tray icon's right-click context menu.

The last two require a previous capture in the current session. If none exists, or the previously captured window is closed or minimized, a warning toast is shown. Direct clipboard captures honor capture.include_cursor and do not open the overlay.

overlay: annotation tools

overlay: general

text editing

pinned images

configuration

greenflame reads its config from:

%USERPROFILE%\.config\greenflame\greenflame.json

The tables below list the available settings and their defaults. You only need to supply the values you want to change.

capture settings (capture.*)

UI settings (ui.*)

tool settings (tools.*)

save settings (save.*)

filename patterns

Filenames use Greenshot-style ${VARIABLE} placeholders:

example configuration

{
  "capture": {
    "include_cursor": true
  },
  "ui": {
    "show_balloons": true,
    "tool_size_overlay_duration_ms": 800
  },
  "tools": {
    "font": {
      "sans": "Arial",
      "serif": "Times New Roman",
      "mono": "Courier New",
      "art": "Comic Sans MS"
    },
    "colors": { "4": "#ff00ff" },
    "current_color": 0,
    "brush": { "size": 2, "smoothing_mode": "smooth" },
    "highlighter": {
      "opacity_percent": 33,
      "pause_straighten_ms": 800
    },
    "obfuscate": { "block_size": 10, "risk_acknowledged": true },
    "text": {
      "size": 14,
      "current_font": "sans",
      "spell_check_languages": ["en-US"]
    }
  },
  "save": {
    "default_save_dir": "C:\\Users\\you\\Pictures\\greenflame",
    "default_save_format": "png",
    "filename_pattern_window": "screenshot-${YYYY}-${MM}-${DD}_${hh}${mm}${ss}-${title}"
  }
}