CROSSMACRO(1)

💖 NAME 💖

crossmacro(1) is the manual for crossmacro — your keyboard and mouse macro automation CLI. Bestie, it's giving "control your whole input flow from the terminal" energy, and I'm obsessed. ✨

---

✨ SYNOPSIS ✨

crossmacro [-h|--help] [-v|--version] [--start-minimized]
crossmacro (no arguments) starts GUI mode
crossmacro play MACRO_FILE [--speed N] [--loop] [--repeat N] [--repeat-delay-ms MS] [--countdown SEC] [--timeout SEC] [--dry-run] [--json] [--log-level LEVEL]
crossmacro macro validate MACRO_FILE [--json] [--log-level LEVEL]
crossmacro macro info MACRO_FILE [--json] [--log-level LEVEL]
crossmacro doctor [--verbose] [--json] [--log-level LEVEL]
crossmacro settings get [KEY] [--json] [--log-level LEVEL]
crossmacro settings set KEY VALUE [--json] [--log-level LEVEL]
crossmacro schedule list [--json] [--log-level LEVEL]
crossmacro schedule run TASK_ID [--json] [--log-level LEVEL]
crossmacro shortcut list [--json] [--log-level LEVEL]
crossmacro shortcut run TASK_ID [--json] [--log-level LEVEL]
crossmacro record (--output|-o) MACRO_FILE [--mouse BOOL] [--keyboard BOOL] [--mode auto|absolute|relative] [--skip-initial-zero] [--duration SEC] [--json] [--log-level LEVEL]
crossmacro run [--step STEP]... [--file STEPS_FILE] [--speed N] [--countdown SEC] [--timeout SEC] [--dry-run] [--json] [--log-level LEVEL]
crossmacro run STEP_COMMAND [STEP_COMMAND]... [--file STEPS_FILE] [--speed N] [--countdown SEC] [--timeout SEC] [--dry-run] [--json] [--log-level LEVEL]
crossmacro headless [--json] [--log-level LEVEL]
crossmacro --headless [--json] [--log-level LEVEL]

🦋 DESCRIPTION 🦋

CrossMacro gives you GUI and CLI workflows for macro playback, validation, recording, environment diagnostics, and background headless runtime. If no CLI command is provided, CrossMacro starts GUI mode. Slay. 💅

On Linux, CrossMacro can run in two different input modes. The preferred packaged path is daemon-backed mode, where the app talks to crossmacro.service over /run/crossmacro/crossmacro.sock and the daemon service user owns device access. The desktop user must be a member of the crossmacro group to use that socket.

⚠️ After adding a user to the group, log out and back in or reboot before starting CrossMacro again, because existing sessions keep their old group list. No cap, that part matters.

Some channels and environments intentionally support direct device mode instead, where the app process itself needs access to /dev/uinput and, for recording or hotkeys, readable /dev/input/event* devices. Direct device readiness does not fix daemon socket permission failures.

On X11, CrossMacro tries native X11 capture and playback first; a supported native X11 session does not require daemon-backed or direct device fallback. Flatpak Wayland is hybrid: it uses the exposed host daemon socket when available and falls back to direct device mode only when the needed device permissions are present.

Arch and CachyOS package hooks provision the crossmacro sysusers entry before service start or restart, and print manual remediation when they cannot confirm adding the installing user to the crossmacro group automatically. Wayfire IPC discovery checks WAYFIRE_SOCKET, then XDG_RUNTIME_DIR, then temp-directory socket candidates. 🧚

🎀 OPTIONS 🎀

• -h, --help — Show command help.
• -v, --version — Show version.
• --start-minimized — Start GUI minimized. When tray support is available, CrossMacro starts hidden to tray instead.
• --json — Print command output as JSON.
• --log-level LEVEL — Override logging level for the current command. Supported values: Verbose, Debug, Information, Warning, Error, Fatal.

🧭 HELP AND ROUTING POLICY 🧭

• crossmacro --help — Shows top-level help.
• crossmacro <command> --help — Shows help for that command topic (for example run or record).
• Standalone command options — Standalone CLI-only options such as --json and --log-level require a command and return exit code 2.
• Non-CLI startup switches — Known GUI startup switches are routed to GUI startup (for example --start-minimized, --drm, --fbdev, --display, Finder-style -psn_*).
• Unknown tokens — Unknown commands/options return CLI parse error (exit code 2) instead of falling through to GUI.

🔁 OPTION ALIASES 🔁

• record --output, -o — Both forms are accepted; one is required for output path selection.
• headless, --headless — Both forms start headless runtime mode.

📏 VALUE RULES 📏

• play — --repeat, --repeat-delay-ms, --countdown, and --timeout must be >= 0. Providing --loop without --repeat means infinite loop mode. Providing --repeat with value > 0 implies loop semantics for that playback run. --repeat 0 requires --loop (infinite mode).
• run — --speed must be between 0.1 and 10.0. --countdown and --timeout must be >= 0.
• record — --duration must be >= 0, and at least one of --mouse or --keyboard must be true.

🕹️ COMMANDS 🕹️

• play — Load and play a macro file without starting GUI.
• macro validate — Validate macro syntax and playback compatibility.
• macro info — Show macro metadata and event breakdown.
• doctor — Run environment and input capability diagnostics. On Linux, daemon-backed checks and direct device checks are reported separately. With --json, inspect daemon-specific details such as socket status, required group, current process groups, session membership, and remediation. Direct input readiness can pass while daemon IPC still warns or fails.
• settings get|set — Read or update scriptable settings keys.
• schedule list|run — Inspect schedule tasks or trigger a schedule task manually.
• shortcut list|run — Inspect shortcut tasks or trigger a shortcut task manually.
• record — Record input events and save a macro file.
• run — Run inline event steps directly from CLI (without a .macro file). Supported steps: move abs|rel, down, up, click, scroll, key down|up, tap, delay, type, set variables, inc/dec counters, repeat blocks, if/else, while, and for blocks, screen-reading steps pixelcolor, waitcolor, and pixelsearch, plus loop control with break and continue. Randomized timing is supported with delay random <min> <max> or delay random <min>..<max>.
• headless — Run background services without GUI (hotkeys, scheduler, shortcuts, text expansion) until interrupted. Recording hotkey toggles capture start/stop. Playback hotkey toggles play/stop for the last macro recorded in the same headless session. Pause hotkey toggles pause/resume for active playback.

🔎 Screen-reading syntax 🔎

pixelcolor <x> <y> [var]
pixelcolor rel <dx> <dy> [var]
waitcolor <x> <y> <RRGGBB|$var> [timeout_ms] [result_var]
pixelsearch <x1> <y1> <x2> <y2> <RRGGBB|$var> [found_var var_x var_y|var_x var_y] [tolerance <0..255>]

Use RRGGBB for a literal target color, or $var to reuse a color previously written by pixelcolor. Bare variable names are not accepted as target colors. 🎨

🚪 EXIT STATUS 🚪

• 0 — Success.
• 2 — Invalid arguments or parsing error.
• 3 — File access/read error.
• 4 — Macro validation error.
• 5 — Environment/permission/runtime readiness error.
• 6 — Runtime playback or capture error.
• 130 — Interrupted by signal (for example Ctrl+C).

🌟 EXAMPLES 🌟

• Play a macro file three times.

crossmacro play ./demo.macro --speed 1.25 --repeat 3

• Run diagnostics and print JSON.

crossmacro doctor --json

• Compile and validate direct run steps without sending input.

crossmacro run --step move abs 800 400 --step click left --dry-run

• Force click at live cursor even after absolute moves.

crossmacro run --step move abs 800 400 --step click current left

• Execute chained inline run steps in sequence.

crossmacro run move rel 100 0 delay 30 click left

• Run a repeated block with variable substitution and randomized delay.

crossmacro run --step set n=3 --step repeat $n { --step click left --step delay random 20 50 --step }

• Run a bounded while loop with explicit counter increment.

crossmacro run --step set i=0 --step while $i < 10 { --step click left --step inc i --step }

• Run a for loop with custom step value.

crossmacro run --step for n from 1 to 5 step 2 { --step click right --step }

• Load run steps from a plain text file (one step per line, '#' comments allowed).

crossmacro run --file ./steps.txt

• Start headless runtime and keep running until interrupted.

crossmacro headless

• Start GUI hidden to tray when tray icon support is available for the current session.

crossmacro --start-minimized

👀 SEE ALSO 👀

Project repository: https://github.com/alper-han/CrossMacro

---

💖 That's the whole vibe! Source/version: CrossMacro · date: 2026-02-28 · manual: CROSSMACRO(1). Byeee! 💖