JoyPro2 Discord GitHub
Engine (CLI)

engine devices

Show:

10 commands of engine devices. Each with every option and every value it takes, what it does, which GUI buttons use it, and an example.

#engine devices list

written
engine devices list [--connected] [--profile-devices]
For beginners

Lists device names: the connected game controllers and the devices your profile has binds for, and which are only in one list. List Devices in Settings > Devices and Refresh Options on the Binds page run it.

engine devices list --connected --profile-devices --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced
  • No flag (or both): both lists. --connected: only the connected devices; --profile-devices (also --profile-only, --in-profile): only the profile's.
  • The names are as JoyPro writes them into binds, with the instance GUID.
  • Read-only.
Technical internals

What it does Lists connected devices and/or devices referenced in profile data.

OptionValuesMeaning
--connectedswitch (no value)For devices list, show connected devices only.
--profile-devicesswitch (no value)For devices list, show profile-referenced devices only.

Used by the GUI Profile bar: Reload · Profile bar: Undo · Start: Refresh · Start: Refresh DCS · Start: Refresh IL-2 · Start: Refresh Star Citizen · Start: List Devices · Binds: Refresh Options · Settings: Look again · Settings: Remove · Settings: List Devices · Settings: Exchange Device

Example

engine devices list --connected --text
engine devices list --profile-devices --text
How the options interact
  • No flag shows both connected and profile devices.
  • --connected and --profile-devices let you limit one side.

#engine devices inputs

written
engine devices inputs [--include-off]

Aliases: catalog, input-catalog

For beginners

Lists every input name JoyPro knows: joystick axes, buttons and hat directions, and the keyboard keys in DirectInput, DCS and IL-2 spelling. Input Catalog in Settings > Devices and the input list on the Binds page use it.

engine devices inputs --text
Advanced
  • --include-off adds the _OFF form of each joystick input.
  • Read-only; no profile needed.
Technical internals
  • Output: JoystickAxes, JoystickButtons, JoystickPovButtons, JoystickOffVariants, KeyboardDirectInput, KeyboardDcs, KeyboardIl2, Warnings; exit code 0.
  • Aliases: devices catalog, devices input-catalog.

What it does Lists full supported input-token catalogs (joystick axes/buttons/POV and keyboard key names for DCS/IL2).

OptionValuesMeaning
--include-offswitch (no value)For devices inputs, include _OFF release variants for joystick axis/button/POV tokens.

Used by the GUI Binds: Refresh Options · Settings: Input Catalog

Example

engine devices inputs --text
engine devices inputs --include-off --text
How the options interact
  • Outputs canonical joystick and keyboard token catalogs in JSON (default) or text (--text).
  • Use --include-off to include _OFF release variants for joystick inputs.
  • Keyboard section includes DCS-style tokens and IL2 key_* tokens for binds set --format il2.

#engine devices exchange

written
engine devices exchange <old-device> <new-device> [--old <name>] [--new <name>] [--confirm true|false]

Alias: swap; renames the device, inputs stay

For beginners

Moves everything of one device in the profile to another device with the same inputs: binds, modifiers and the device's settings. Use it when a stick got a new Windows ID or you replaced it with the same model. Exchange Device in Settings > Devices runs it (it asks first and keeps a copy of the profile).

engine devices exchange "LEFT VPC Stick WarBRD" "L-VPC Stick WarBRD" --confirm false --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced
  • Old and new device: positional, or --old (--from, --device) and --new (--to, --target).
  • The old device must be one the profile uses. A name that does not match exactly is resolved to the closest device; --confirm true (default) asks on the console, --confirm false takes it and says so on stderr.
  • A new device given with its instance GUID is taken as written (also when it is not connected).
  • Input names stay unchanged. Also moved: bind backups and aliases, modifiers on the device, the device's alias, layout file, force feedback settings and activity entries.
  • For other models, input by input with a preview: engine devices replace.
Technical internals
  • Output: the counts per kind and UpdatedRelations; exit code 0.
  • Failures (exit 1): devices exchange requires <old-device> <new-device> (or --old/--new)., No profile-referenced devices are available to exchange., devices exchange source and target resolve to the same device: '...'., No profile references were updated for device '...'.
  • One undo step with --profile. The game gets the new device at the next export.

What it does Replaces one device name with another across profile binds, modifiers, and device metadata.

OptionValuesMeaning
--old<name>Source device name for devices exchange. Example: --old 'LEFT VPC Throttle'.
--new<name>Target device name for devices exchange. Example: --new 'RIGHT VPC Throttle'.
--confirmtrue falseControls suggestion confirmation (true) vs auto-accept (false).
Every value as a command line
engine devices exchange --confirm true
engine devices exchange --confirm false

Used by the GUI Settings: Exchange Device

Example

engine --profile 'C:\JoyPro\profiles\pilot_main.pr0file' devices exchange 'LEFT VPC Throttle' 'RIGHT VPC Throttle' --confirm false --text
How the options interact
  • Accepts positional or named options --old/--new.
  • Use --confirm false to auto-accept closest device suggestions for fuzzy names.
  • Updates binds, modifiers, and profile device metadata keys in one operation.

#engine devices replace

written
engine devices replace <old-device> <new-device> [--old <name>] [--new <name>] [--mode auto|same|layout] [--map OLD=NEW]... [--merge add|keep|replace] [--grip <device>=<grip id>]... [--dry-run]

Moves binds and modifiers input by input: same = the same input ids, layout = by the part on the device (device catalog), auto = same for the same product, else layout; --merge where the new device already has a bind on the input: add = both stay (default), keep = the new device's bind wins, replace = the old device's bind wins; --old/--from and --new/--to name the devices instead of the positions; --dry-run previews

For beginners

Moves every bind and modifier of one device to another device, input by input, also to a different model: the same input ids for the same product, else by the device's parts (trigger to trigger, hat 2 to hat 2). The Replace device window runs it with --dry-run for the preview and without for Move binds; it opens from Replace device..., a device card's Replace... or Replace the selected bind's device... in the binds list's menu.

engine devices replace "Joystick - HOTAS Warthog" "VKB Gladiator NXT EVO" --dry-run --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced
  • Old device: one the profile has binds on (its full name, or the name without GUID when only one device has it). New device: a connected device, a device of the profile, or any name with an instance GUID. Also --old / --from and --new / --to.
  • --mode auto (default): same when it is the same product (same name, USB id or catalog model), else layout (the parts of the device catalog). same or layout forces one (GUI: Same input ids (1:1), By layout (device catalog)).
  • --map OLD=NEW (repeatable): your choice for one input; NEW = none leaves it on the old device. An axis goes only to an axis, a button only to a button or hat direction.
  • --grip <device or VID:PID>=<grip id> (repeatable): which grip a base carries.
  • --merge when the new device already has binds: add keeps both, keep lets the new device's binds win (the old bind stays on the old device), replace lets the old device's binds win (the new device's binds on those inputs are removed); the word may be written in any case (ADD = add). A real run with such overlaps and no --merge is refused.
  • Inputs that do not fit stay on the old device. When nothing is left on it, its alias, force feedback settings and activity move along (its picture and USB id only for the same product).
  • --dry-run shows the plan and saves nothing.
Technical internals
  • Output: JSON plan (OldDevice, NewDevice, Mode, ModeReason, OldModel, NewModel, connected flags, bind counts, NeedsMergeChoice, Mappings with old and new input, part, method, relations and modifiers, NewInputs, Steps, Warnings), or text Device Replace (preview) / (applied); exit code 0.
  • Failures (exit 1): The profile has no binds on '...'. Devices with binds: ..., '...' is neither connected nor in the profile. Connected: ..., The old and the new device are the same device: ..., ... already has <n> bind(s). Choose how to merge: ..., No input of ... fits ...; nothing was moved. Map inputs yourself with --map OLD=NEW., --mode must be auto, same or layout., --merge must be add, keep or replace.
  • One undo step with --profile (not for a dry run). Reference: devices. Related: engine devices exchange (same inputs, everything at once), engine devices auto-remap.

What it does Moves the binds and modifiers of one device to another, input by input: same = the same input ids, layout = by the part on the device (device catalog), auto (default) = same for the same product, else layout. --merge decides where the new device already has a bind on the input: add = both stay (default), keep = the new device's bind wins, replace = the old device's bind wins. --old/--from and --new/--to name the devices instead of the positions; --dry-run previews.

OptionValuesMeaning
--old<name>The old device instead of the first position (also --from).
--new<name>The new device instead of the second position (also --to).
--modeauto same layoutHow inputs are matched: same = the same input ids, layout = by the part on the device (device catalog), auto (default) = same for the same product, else layout.
--mapswitch (no value)Your own match for one input, OLD=NEW (NEW = none leaves the input out); repeatable. Example: --map JOY_BTN3=JOY_BTN5.
--mergeadd keep replaceWhere the new device already has a bind on the input: add = both stay (default), keep = the new device's bind wins (the old one stays on the old device), replace = the old device's bind wins (the new device's bind there is removed).
--grip<device>The grip on a base (device or VID:PID = grip id), for the layout match.
--dry-runswitch (no value)Show the plan (every input's match); the profile is not changed.
Every value as a command line
engine devices replace --mode auto
engine devices replace --mode same
engine devices replace --mode layout
engine devices replace --merge add
engine devices replace --merge keep
engine devices replace --merge replace

Example

engine --profile 'C:\JoyPro\profiles\pilot_main.pr0file' devices replace 'Old Stick' 'New Stick' --dry-run --text
engine --profile 'C:\JoyPro\profiles\pilot_main.pr0file' devices replace --from 'Old Stick' --to 'New Stick' --mode layout --merge keep --text

#engine devices copy-to

written
engine devices copy-to <device-A> <device-B> [--mode auto|same|layout] [--map OLD=NEW]... [--grip <device>=<grip id>]... [--merge skip|add] [--dry-run]

Not with --multi-bind off: every bind of A gets the matching input of B as one more input of the same relation, matched like devices replace; A keeps its binds; an input of B another relation uses is left out unless --merge add; --dry-run previews; one undo step

For beginners

Every bind of device A also gets the matching input of device B, in the same relations (the same grip on two bases). Device A keeps its binds. Copy every bind of a device to another device on the Binds page runs it (Preview, then Copy).

engine devices copy-to "L-VPC Stick MT-50CM2 {...}" "MOZA AB9 Base {...}" --dry-run --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced
  • Inputs are matched like engine devices replace: the same ids for the same product (--mode same), else by layout (--mode layout, --grip <device>=<grip id>), --map OLD=NEW for your own choices.
  • An input of B another relation uses is left out (warning) unless --merge add; inputs the relation has already are counted as "already there". One profile version: Ctrl+Z undoes the whole copy.

What it does Not with --multi-bind off: every bind of A gets the matching input of B as one more input of the same relation, matched like devices replace; A keeps its binds; an input of B another relation uses is left out unless --merge add; --dry-run previews; one undo step.

OptionValuesMeaning
--modeauto same layoutExport mode for DCS/IL2 export commands: clean, add, merge, merge-overwrite.
--mapswitch (no value)
--grip<device>
--mergeskip addMerge import results into existing in-memory profile.
--dry-runswitch (no value)Report what the command would do; nothing is written or changed.
Every value as a command line
engine devices copy-to --mode auto
engine devices copy-to --mode same
engine devices copy-to --mode layout
engine devices copy-to --merge skip
engine devices copy-to --merge add

Used by the GUI Binds: Preview · Binds: Copy

Example

engine devices copy-to <device-A> <device-B> --text

#engine devices auto-remap

written
engine devices auto-remap [--dry-run]

Alias: remap; a profile device that is not connected gets the connected device of the same product with a new GUID

For beginners

Gives a device that came back under a new Windows ID (new PC, Windows reinstalled, other USB port) its binds again: a profile device that is not connected gets the connected device of the same product. JoyPro runs it after opening a profile when Remap Missing Devices is on, and shows what moved with Undo.

engine devices auto-remap --dry-run --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced
  • A pair: the same USB id JoyPro remembered for the old device, or the same name (and the same USB id when one is known); the connected device must not be used in the profile yet.
  • Several connected devices of one kind: the only one that has every input the profile uses; else the device is skipped with the candidates (pick one with engine devices replace). Two old devices for one connected device are skipped too.
  • A pair is moved like engine devices exchange (binds, modifiers, the device's settings), and the new device's USB id is remembered.
  • --dry-run lists the pairs and changes nothing. Alias: devices remap.
Technical internals
  • Output: JSON DryRun, Applied, Remapped (OldDevice, NewDevice, Reason, Binds, Modifiers), Skipped (OldDevice, Reason, Candidates), Missing, Warnings, or text Device Auto Remap; exit code 0.
  • Failures (exit 1): Unknown devices auto-remap argument(s): ...
  • The profile is saved (one undo step) only when something moved.

What it does A profile device that is not connected gets the connected device of the same product with a new GUID (alias: remap); --dry-run previews.

OptionValuesMeaning
--dry-runswitch (no value)Report what the command would do; nothing is written or changed.

Example

engine devices auto-remap --text

#engine devices remove

written
engine devices remove <device-name> [--device <name>] [--confirm true|false]

Aliases: purge, clear

For beginners

Removes one device from the profile: every bind on it, its modifiers and its settings. The relations stay, unbound. Remove Device Refs in Settings > Devices runs it (it asks first and keeps a copy of the profile).

engine devices remove "Throttle - HOTAS Warthog" --confirm false --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced
  • One device per run (positional or --device). With its GUID only that instance matches: a second unit of the same model keeps its binds.
  • Removed: the binds whose device it is, modifiers of that device on other binds and in the modifier list, its alias, layout file, force feedback settings and activity entries.
  • Several inputs per relation: an extra input on the device goes; when the main bind is on the device and the relation has another input, that input becomes its main bind (the relation stays bound).
  • --confirm as for engine devices exchange.
  • After the next export the device has no binds from JoyPro.
Technical internals
  • Output: the counts per kind, UpdatedRelations, ModifiersWithoutBinds; exit code 0.
  • Failures (exit 1): devices remove requires <device-name> or --device <name>., devices remove accepts one target device at a time., No profile references were removed for device '...'.
  • Aliases: devices purge, devices clear. One undo step with --profile.

What it does Removes all references to one device from profile binds, modifiers, and device metadata.

OptionValuesMeaning
--device<name>Include one device per flag. Example: --device LEFT VPC Throttle.
--confirmtrue falseControls suggestion confirmation (true) vs auto-accept (false).
Every value as a command line
engine devices remove --confirm true
engine devices remove --confirm false

Used by the GUI Settings: Remove · Settings: Remove Device Refs

Example

engine --profile 'C:\JoyPro\profiles\pilot_main.pr0file' devices remove 'LEFT VPC Throttle' --confirm false --text
How the options interact
  • Removes one target device at a time.
  • Removes matching bind assignments and modifier references, then prunes profile metadata entries for that device.

#engine devices alias list

written
engine devices alias list | set <device> <alias> | clear <device>

A name of your own for a device; display only, exports use the real device

For beginners

A name of your own for a device ("Left throttle"): list, set or clear it. It is for display only; exports always use the real device. Name it beside the box "Your name for this device" runs set, the clear button next to it clear.

engine devices alias set "LEFT VPC Throttle" "Left throttle" --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced
  • list (default): every device with an alias. A stored name that is only the device's own name, or the name of a layout template an older JoyPro kept there, is no alias and left out.
  • set <device> <alias> (or --device, --alias; the remaining words form the alias): one line, at most 60 characters. clear <device> (also remove) takes it back.
  • The device: a full name with instance GUID, a device of the profile, or the connected device a name resolves to. A name without GUID finds the alias of the only device of that name.
  • A device that comes back under a new ID keeps its alias: engine devices auto-remap, engine devices exchange and engine devices replace move it.
Technical internals
  • Output: JSON Aliases (Device, Alias), or for set / clear Action, Device, Alias, PreviousAlias, Changed; text Device alias: <device> = <alias>; exit code 0.
  • Failures (exit 1): devices alias set requires <device> <alias>., devices alias set requires an alias (devices alias clear <device> removes one)., Unknown devices alias action: ... (list, set, clear).
  • Stored in the profile; set and clear are one undo step (none when nothing changed). Alias: devices aliases.

What it does Names of your own for devices (display only; exports use the real device): list them, set one, or clear one.

Example

engine devices alias list --text

#engine devices kb

written
engine devices kb [list [words] | show <id> | identify [--grip <device>=<grip id>]... [--add-device <id>]...]

Device catalog for Auto Assign; list: the devices whose id, name or maker contains every word

For beginners

JoyPro's device catalog for Auto Assign: search it, show one model's controls, or identify your connected devices against it. Auto Assign on the Binds page runs identify when it opens, list for Search Catalog and show for Layout.

engine devices kb list "Orion" --text
Advanced
  • list [words]: catalog entries whose id, name or vendor contain every word (as one quoted argument or several); list vkb gladiator finds the entries with both words.
  • show <id>: one model with its axes and controls (input, control, label).
  • identify [--grip <device>=<grip id>]... [--add-device <id>]...: the connected devices identified against the catalog; --grip picks the grip of a base that takes several, --add-device adds a catalog device that is not connected.
  • Read-only; no profile needed.
Technical internals
  • Output: JSON (list: id, name, vendor, kind, hand, base, image, confidence, VID:PIDs; show: the model; identify: the devices), or text; exit code 0.
  • Failures (exit 1): devices kb show requires a device id., Device '...' is not in the device catalog., Unknown devices kb action: ....
  • The catalog: DB\Devices in JoyPro's program folder. Reference: auto-assign. Related: engine relations auto-assign.

What it does The device catalog Auto Assign uses: list (devices whose id, name or maker contains every word of the query), show <id> (its axes and controls), identify (how the connected devices were recognised, grip choices).

OptionValuesMeaning
--grip<device>
--add-device<id>

Used by the GUI Binds: Put relations on my buttons automatically... · Binds: Detect Devices · Binds: Layout · Binds: Search Catalog · Binds: Show Layout

Example

engine devices kb list vkb gladiator --text
engine devices kb identify --text

#engine devices reference

written
engine devices reference [list [query] | identify --vidpid <VID:PID> --name <HID name> [--instance <name>] [--buttons <n>] [--hats <n>] [--axes X,Y,RZ] | show <id> [--base <id>] [--svg <file>] [--light] [--no-badges] | check [query] | photos [query] [--coverage] | photo-add --model <id> --url <https photo on the maker's host or an allowed review site> --view <front|side|back|top|base|three-quarter|sheet> [--page <url>] [--confidence <c>] [--shows a,b] [--sha256 <hex>] [--source maker|review|commons] [--site <name>] [--licence <note>] [--archive <web.archive.org url>] [--width <px>] [--height <px>] | layout-check | drawings [query] [--check] [--model <id> [--view <v>] --svg <file> | --png <file>] [--light] [--drawing-style lines|cel] [--drawing-preset <p>] | completeness [query] [--missing] [--list <file>] | mesh-render --aircraft <plane> --grip stick|throttle [--view <yaw>,<pitch>] [--size <px>] [--skip <regex>] --folder <dir> | detect <model> [--photo <file|view|sha>] [--photos <folder>] [--max <n>] [--eval]]

Device reference pictures: catalog, identification and the question to ask, JoyPro's schematic with markers, photo references, curated marker positions (layout-check: exit code 1 on a problem), JoyPro's own drawings of the devices, whether every input has a position, a game's grip rendered for a drawing, detect: where the controls of a device photo probably are (experimental)

For beginners

JoyPro's device reference catalog: search its models, identify a device from its USB id and name, or draw JoyPro's schematic of a model with numbered markers where its parts are.

engine devices reference identify --vidpid 044F:0402 --name "Joystick - HOTAS Warthog" --text
Advanced
  • list [words] (default): the models with kind, shape, known inputs, VID:PIDs and origin (catalog, or user for your own definitions).
  • identify --vidpid <VID:PID> --name <HID name> [--instance <name>] [--buttons <n>] [--hats <n>] [--axes X,Y,RZ]: the matching model, method and reason, its base, the grips to choose from, and, when it is not sure, the question to ask with ranked candidates.
  • show <id> [--base <id>] [--svg <file>] [--light] [--no-badges]: the schematic's markers (number, name, type, region, position, inputs); --svg writes it (dark unless --light).
  • photos [words] [--coverage]: the reference photos per model and the curated position sets; --coverage only the numbers.
  • drawings [words]: JoyPro's line drawings and how many curated positions each carries; drawings --model <id> [--view <v>] --svg <file> | --png <file> [--light] [--drawing-style lines|cel] [--drawing-preset <p>] draws one.
  • completeness [words] [--missing] [--list <file>]: whether the best shipped picture of a model places every input.
  • detect <model> [--photo <file|view|sha>] [--photos <folder>] [--max <n>] [--eval] (experimental): where the buttons, hats, switches and knobs of a device photo probably are, each with a score; no input is assigned.
  • Checks of the catalog for its maintainers: check [words], layout-check, drawings --check. photo-add adds a photo reference (an address on the maker's hosts or an allowed site) to DB\DevicePhotos; mesh-render renders a game's stick or throttle grip into buffers a drawing is made from.
  • Files are written only by --svg, --png, photo-add and mesh-render. The profile is not used.
Technical internals
  • Output: JSON or text per action; exit code 0, 1 when check, layout-check or drawings --check find problems.
  • Failures (exit 1): devices reference identify needs --vidpid and/or --name., devices reference show needs one model id., Device '...' is not in the device catalog., JoyPro has no line drawing of '...'., Unknown devices reference action: ...
  • The catalog: DB\Devices in JoyPro's program folder plus your own definitions in %LOCALAPPDATA%\JoyPro2\Devices. Alias: devices ref. Reference: device-reference. Related: engine devices kb, engine layout identify, engine layout callouts.

What it does Device reference pictures (docs/device-reference.md): list and identify catalog models, show JoyPro's schematic, check and list photo references, add one (photo-add), check the curated marker positions (layout-check, exit code 1 on a problem), JoyPro's own drawings (drawings), whether every input has a position (completeness), a game's grip rendered for a drawing (mesh-render) and, experimental, where the controls of a device photo probably are (detect).

OptionValuesMeaning
--vidpid<VID:PID>
--name<HID name>Name value for commands that create/merge entities. Example: --name 'Merged Startup'.
--instance<name>
--buttons<n>
--hats<n>
--axesswitch (no value)
--base<id>
--svg<file>
--lightswitch (no value)
--no-badgesswitch (no value)
--coverageswitch (no value)
--model<id>
--url<https photo on the maker's host or an allowed review site>
--view<front|side|back|top|base|three-quarter|sheet>
--page<url>
--confidence<c>
--showsswitch (no value)
--sha256<hex>
--sourcemaker review commons
--site<name>
--licence<note>
--archive<web.archive.org url>
--width<px>
--height<px>
--checkswitch (no value)
--png<file>
--drawing-stylelines celJoyPro's drawings of the devices: lines (line art) or cel (shaded). Default: the GUI's setting.
--drawing-preset<p>The colours of JoyPro's drawings: joypro, manual, blueprint, print or custom (then --drawing-ink / --drawing-paper / --drawing-accent). Default: the GUI's setting.
--missingswitch (no value)For db list, show only missing entries.
--list<file>For support bundle: only print what the zip would hold; nothing is written.
--aircraft<plane>MSFS export only: also write the relations limited to this aircraft (key from DB\\MSFS\\aircraft.tsv); the sim's presets apply to every aircraft.
--gripstick throttle
--size<px>
--skip<regex>
--folder<dir>
--photo<file|view|sha>
--photos<folder>
--max<n>
--evalswitch (no value)
Every value as a command line
engine devices reference --source maker
engine devices reference --source review
engine devices reference --source commons
engine devices reference --drawing-style lines
engine devices reference --drawing-style cel
engine devices reference --grip stick
engine devices reference --grip throttle

Example

engine devices reference [list --text