Docs

RunMacro Documentation

Learn RunMacro from basics to advanced.

Everything you need to start and master RunMacro — from basic commands to advanced automation workflows.

Ctrl K

📦 Features

Package a macro and its resources as a portable PMacro project

In RunMacro Studio, save the root macro, use File › Check dependencies... as advisory evidence, then choose File › Package project.... The analyzer can falsely flag a current protected/app-key QMacro because it expects macro.json, even when the exporter can package it. Test the archive in a clean folder and remember that editable PMacro contents are readable as ZIP.

Prerequisites

Studio must contain at least one workflow command; an empty project cannot be packaged.
Save the root PMacro and its editable children first so relative paths have the correct owning-directory base.
Referenced PMacro/QMacro files, Find Image assets and selector profiles must exist and be readable.
An app-key QMacro child can be repackaged, but a password-protected child QMacro cannot be recursively embedded.
The destination must be writable and have room for the archive and any overwrite backup.
Remove credentials, cookies and private data from commands and metadata before giving the package to anyone.

Supported modes

Desktop Mode — Packaging is a Studio action available while the workspace is in Desktop Mode. The archive preserves mode metadata; it does not translate Desktop commands into Browser commands.
Browser Mode — Studio can package a Browser Mode workflow. Commands, used selectors and images travel, but Chrome profiles, cookies, provider applications, local APIs and browser state remain external prerequisites.

What it does

Package Project writes an editable .pmacro archive. Inside are readable macro.json data, manifests, used selector profiles, images and a submacros/ tree when required. RunMacro follows PMacro calls, QMacro calls, Window Watcher run-macro handlers and Find Image assets recursively, copies each resolvable dependency under a collision-resistant package name, and rewrites the packaged command references. The open source workflow remains untouched. An ordinary PMacro save keeps child macros external; both Project packaging and QMacro export recurse, but only QMacro seals command and resource bytes in an encrypted payload.

When to use it

Move a workflow with nested child macros and images to another computer without copying every dependency by hand.
Hand an editable Studio project to a collaborator instead of distributing a runner-oriented QMacro.
Create and clean-test an intended self-contained archive of a PMacro/QMacro tree before archiving or support handoff.
Consolidate resources from several folders into one archive whose packaged references point internally.

When not to use it

Confidential logic, credentials or customer data must remain secret; a Project package provides no encryption boundary.
The deliverable should open as a controlled QMacro Runner experience with metadata, inputs, Safe Mode or a password; use Export QMacro instead.
Dependencies are produced by custom code or dynamic data rather than recognized command fields; automatic discovery cannot cover arbitrary runtime files.
Several authors need merging, version history or live updates; this package is a snapshot, not source control or Cloud Sync.

Configuration steps

Open the root workflow in RunMacro Studio, test it, and save it to disk. Save editable child macros too so every relative reference has a stable owner directory.
Choose File › Check dependencies... to inspect recognized fields, but treat the report as advisory: the analyzer currently expects macro.json and cannot reliably inspect a protected/app-key QMacro.
Resolve real missing files, cycles, over-deep chains, and password-protected child QMacros. If an app-key child is flagged only for missing macro.json, record the possible false positive and rely on exporter behavior plus clean-folder testing.
Choose File › Package project.... This is separate from Export as QMacro... and there is no protection or run-configuration dialog.
In Save As, select a destination and filename. Studio proposes workflow-project.pmacro or <current-name>-project.pmacro, starts in Downloads and appends .pmacro when needed.
Read the export preflight. Choose No for a genuinely missing item; a protected/app-key QMacro reported only as lacking macro.json can be a false positive even when the exporter packages it. If you continue, test with the old source unavailable.
RunMacro recursively copies resolvable children, assigns collision-resistant names under submacros/ and images/, records resource hashes, and rewrites only the packaged copies.
Wait for the success message. An existing destination is replaced atomically and its previous bytes are copied to a neighboring .bak file; the open Studio document remains the source document.
Move the result to a clean test folder, make the originals unavailable, open the package in Studio and exercise every branch. After editing a received project, run Package Project again rather than relying on ordinary Save.

Every option explained

File › Check dependencies...

Builds an advisory report of paths, command rows, missing files, hashes, selectors, and read errors, normally through five levels. Its reader expects macro.json, so a current protected/app-key QMacro can be flagged even when the exporter can still package it.

File › Package project...

Exports the open workflow as an editable PMacro project. Empty workflows are refused, and the action does not switch the current file, clear dirty state or change Studio mode.

Project filename and destination

Save As uses Editable PMacro project (*.pmacro), opens in Downloads, suggests a -project name and appends the extension when omitted.

Missing-dependency confirmation

A missing item prompts whether to continue, with No selected by default. Continuing leaves the unresolved original path in place, so that branch can fail at runtime.

Recursive child-macro embedding

Always enabled with no checkbox. The exporter follows resolvable Run Macro, Run QMacro, and Window Watcher handlers. For a nested PMacro loaded from an archive, relative references can resolve from its temporary extraction directory rather than the original source location; export may still package correctly even when preflight or displayed paths are misleading.

Images, selectors and resource IDs

Find Image assets and used selector profiles are included. Package filenames receive a short MD5-derived collision suffix, while command resource_id values and manifest records use content SHA-256.

Ordinary PMacro Save versus repackaging

Ordinary PMacro Save does not embed child macros. Opening a project extracts resources temporarily, so a later plain Save can preserve temporary external paths. Use Package Project again for a portable revision.

Export QMacro (separate action)

QMacro also embeds dependencies recursively, but creates an encrypted payload plus Runner metadata and optional password protection. Package Project has none of those controls and prioritizes editability.

Overwrite, temporary file and .bak

When the target exists, RunMacro copies the old file to <name>.bak, writes and fsyncs a temporary file, then atomically replaces the destination.

Expected result

The result is one editable .pmacro archive containing readable macro.json and macro_manifest.json, plus selector_library.json, images/ and submacros/ when used. Recognized references target embedded resources, allowing the tested dependency tree to run without the originals. The archive does not replace the open Studio document and is not encrypted.

Real example

Example: move a three-level workflow with images to another PC

Save main.pmacro, login.pmacro and report.pmacro; let each child use a relative reference to the next level and confirm the Find Image asset exists.
Open main.pmacro, run Check dependencies..., fix real missing items, and recognize that a protected/app-key QMacro macro.json error can be a false positive.
Choose Package project..., save report-project.pmacro, and wait for the embedded-submacro confirmation.
Copy only the resulting archive to a clean machine or folder, then make the three originals unavailable.
Open the project in Studio and execute the login, image and report branches before delivering it with any external environment requirements.

Example: revise a received project without losing portability

Open the received inventory-project.pmacro in Studio and confirm that its embedded child calls execute.
Edit the root or an extracted child and test every affected branch during that session.
Do not treat ordinary File › Save as the final portable deliverable because it disables child embedding and may retain extraction-directory references.
Choose File › Package project... and produce inventory-project-v2.pmacro rather than immediately overwriting the received copy.
Close Studio, move v2 into a clean folder, reopen it and retest before returning the revision.

Limitations and failure cases

An editable PMacro project is plaintext. Opening it as ZIP exposes macro.json, selectors, metadata, paths and images; it is not source protection or a credential vault.
A missing dependency is skipped while its original command path remains. Because the warning can be overridden, a successful write does not prove that every runtime branch is self-contained.
Dependency cycles abort the export without a partial destination, and recursive packaging has a hard ceiling of 10 nested levels.
The normal preflight report scans only five levels by default, so a deeper problem can survive Check Dependencies and fail during archive construction.
Check Dependencies cannot reliably read a current protected/app-key QMacro because its analyzer requires macro.json. This can be a false positive while the exporter successfully decrypts and packages that child, so the report does not reliably cover every dependency type the exporter supports.
A nested PMacro opened from a package can have relative references resolved from a temporary extraction directory. The exporter may still remap and package it correctly, so a temporary preflight path alone proves neither failure nor portability.
A password-protected child QMacro cannot be nested because no child password is available to the exporter. App-key QMacro children can be opened and repackaged by the application.
Relative references in an unsaved workflow have an unstable base: preflight uses a synthetic current-directory owner while packaging can resolve against the selected output path.
Discovery covers recognized Run Macro, Run QMacro, Window Watcher, Find Image and selector fields. Files opened dynamically by Python, code commands or data values are outside that graph.
Child files are remapped to temporary extraction paths when a project is opened. A plain Save after editing can lose self-containment; package the revision again.
Chrome profiles, cookies, provider software, local APIs, fonts, Python modules, licenses, administrator rights, environment variables and network services are not bundled.
Archive validation allows at most 500 entries, 200 MiB total uncompressed data and 50 MiB per member; traversal paths, symlinks, unknown files and case-insensitive collisions are rejected.

Tips & common mistakes

Before sharing, rename a copy to .zip and inspect it exactly as a recipient can. Do not distribute the archive while tokens, passwords or customer data remain.

Save the root and editable children, then use Check dependencies... as one signal rather than a verdict. Always clean-test the package because protected QMacros and temporary extraction paths can mislead preflight.

A normal PMacro keeps child macros external; Project packaging recursively copies readable files; QMacro recursively seals them inside an encrypted payload. Choose by delivery goal, not extension alone.

Override a missing-dependency warning only when that branch intentionally targets a file guaranteed to exist on the destination. The default No is the safe choice.

After editing an opened package, create a -v2 archive with Package Project and test it in a clean folder. Do not merely Save and return the open file.

Verification details

storage/json_store.py
core/macro_path.py
core/macro_dependency_analyzer.py
tests/test_project_package.py
tests/test_phase_b_package.py