Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

add auto-save and dry-run for all session-based softwares on one-shot cmds; highlight the design in cli-anything skill

yuhao18f75791f30b
diff --git a/audacity/agent-harness/cli_anything/audacity/audacity_cli.py b/audacity/agent-harness/cli_anything/audacity/audacity_cli.py
index 21ef8e28b..84f4e9328 100644
--- a/audacity/agent-harness/cli_anything/audacity/audacity_cli.py
+++ b/audacity/agent-harness/cli_anything/audacity/audacity_cli.py
@@ -121,8 +121,10 @@ def handle_error(func):
@click.option("--json", "use_json", is_flag=True, help="Output as JSON")
@click.option("--project", "project_path", type=str, default=None,
help="Path to .audacity-cli.json project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path):
+def cli(ctx, use_json, project_path, dry_run):
"""Audacity CLI — Stateful audio editing from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -140,6 +142,21 @@ def cli(ctx, use_json, project_path):
ctx.invoke(repl, project_path=None)
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
+
+
# -- Project Commands ------------------------------------------------------
@cli.group()
def project():
diff --git a/blender/agent-harness/cli_anything/blender/blender_cli.py b/blender/agent-harness/cli_anything/blender/blender_cli.py
index 668e01f3e..bea340bc0 100644
--- a/blender/agent-harness/cli_anything/blender/blender_cli.py
+++ b/blender/agent-harness/cli_anything/blender/blender_cli.py
@@ -118,8 +118,10 @@ def handle_error(func):
@click.option("--json", "use_json", is_flag=True, help="Output as JSON")
@click.option("--project", "project_path", type=str, default=None,
help="Path to .blend-cli.json project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path):
+def cli(ctx, use_json, project_path, dry_run):
"""Blender CLI — Stateful 3D scene editing from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -137,6 +139,21 @@ def cli(ctx, use_json, project_path):
ctx.invoke(repl, project_path=None)
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
+
+
# ── Scene Commands ──────────────────────────────────────────────
@cli.group()
def scene():
diff --git a/cli-anything-plugin/commands/cli-anything.md b/cli-anything-plugin/commands/cli-anything.md
index 97f0763a6..05ed8a710 100644
--- a/cli-anything-plugin/commands/cli-anything.md
+++ b/cli-anything-plugin/commands/cli-anything.md
@@ -119,6 +119,12 @@ This command implements the complete cli-anything methodology to build a product
/cli-anything https://github.com/blender/blender
```
+## Auto-Save + --dry-run (Required for Session-Based CLIs)
+
+**Session-based CLIs must auto-save after one-shot mutations.** Without this, one-shot commands silently lose changes because `save_session()` is never called before the process exits. A `--dry-run` flag must also be provided to suppress the save.
+
+See [`guides/auto-save-dry-run.md`](../guides/auto-save-dry-run.md) for the full pattern, code examples, and when it applies.
+
## Success Criteria
The command succeeds when:
@@ -132,3 +138,4 @@ The command succeeds when:
8. SKILL.md is generated with proper YAML frontmatter and command documentation
9. setup.py is created and local installation works
10. CLI is available in PATH as `cli-anything-<software>`
+11. **Session-based CLIs implement auto-save + `--dry-run`** (see [guide](../guides/auto-save-dry-run.md))
diff --git a/cli-anything-plugin/guides/auto-save-dry-run.md b/cli-anything-plugin/guides/auto-save-dry-run.md
new file mode 100644
index 000000000..2097bddef
--- /dev/null
+++ b/cli-anything-plugin/guides/auto-save-dry-run.md
@@ -0,0 +1,87 @@
+# Auto-Save + --dry-run for One-Shot Commands
+
+Session-based CLIs must auto-save after one-shot mutations and support `--dry-run` to suppress it.
+
+## Problem
+
+One-shot commands like `cli-anything-kdenlive --project p.json bin import video.mp4` mutate the in-memory project but never call `save_session()`. The project file on disk is unchanged when the process exits — changes are silently lost.
+
+## Solution
+
+Two additions to `<software>_cli.py`:
+
+### 1. Add `--dry-run` to the main CLI group
+
+```python
[email protected](invoke_without_command=True)
[email protected]("--json", "use_json", is_flag=True, help="Output as JSON")
[email protected]("--project", "project_path", type=str, default=None,
+ help="Path to project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
+def cli(ctx, use_json, project_path, dry_run):
+ ...
+```
+
+### 2. Add `@cli.result_callback()` after the group
+
+```python
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
+```
+
+**How it works:**
+- `result_callback` fires once after the CLI group's command chain completes
+- Checks `_repl_mode` (skip in REPL — user saves manually), `dry_run` (skip if set), and `sess._modified` (skip if nothing changed)
+- Calls `sess.save_session()` which uses atomic `_locked_save_json` (see [`session-locking.md`](session-locking.md))
+- Does NOT fire if `sys.exit(1)` was called in `handle_error` (error path) — correct behavior
+
+### Alternative: `ctx.call_on_close` pattern
+
+For harnesses that open the session inline (not via a global singleton), use a closure instead:
+
+```python
+def cli(ctx, use_json, project_path, dry_run):
+ ...
+ if project_path:
+ sess = get_session()
+ proj = proj_mod.open_project(project_path)
+ sess.set_project(proj, project_path)
+
+ def _auto_save():
+ if dry_run:
+ return
+ if sess._modified and sess.project_path and not _repl_mode:
+ sess.save_session()
+
+ ctx.call_on_close(_auto_save)
+```
+
+## `--dry-run` semantics
+
+| Mode | Behavior |
+|------|----------|
+| One-shot (default) | Command executes, output is printed, project is auto-saved |
+| One-shot + `--dry-run` | Command executes, output is printed, project is **not** saved |
+| REPL | `--dry-run` is accepted but ignored (REPL never auto-saves) |
+
+## When this applies
+
+**Required** for any harness where:
+- `core/session.py` exists with `save_session()` and `_modified` tracking
+- The CLI accepts a `--project` flag to load a file-backed project
+- Commands call `sess.snapshot()` before mutations
+
+**Does not apply** to stateless API clients, service wrappers, or harnesses without a persistent project file.
diff --git a/drawio/agent-harness/cli_anything/drawio/drawio_cli.py b/drawio/agent-harness/cli_anything/drawio/drawio_cli.py
index f2ec1d435..875a6fba1 100644
--- a/drawio/agent-harness/cli_anything/drawio/drawio_cli.py
+++ b/drawio/agent-harness/cli_anything/drawio/drawio_cli.py
@@ -130,8 +130,10 @@ def handle_error(func):
@click.option("--json", "json_mode", is_flag=True, help="Output in JSON format")
@click.option("--session", "session_id", default=None, help="Session ID to use/resume")
@click.option("--project", "project_path", default=None, help="Open a project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, json_mode, session_id, project_path):
+def cli(ctx, json_mode, session_id, project_path, dry_run):
"""Draw.io CLI — Diagram creation from the command line.
A stateful CLI for manipulating draw.io diagram files.
@@ -153,6 +155,8 @@ def cli(ctx, json_mode, session_id, project_path):
# Auto-save on exit when --project was used and project was modified
@ctx.call_on_close
def _auto_save():
+ if dry_run:
+ return
if project_path and _session and _session.is_open and _session.is_modified:
_session.save_project()
diff --git a/freecad/agent-harness/cli_anything/freecad/freecad_cli.py b/freecad/agent-harness/cli_anything/freecad/freecad_cli.py
index ca9d1fb39..d940c6884 100644
--- a/freecad/agent-harness/cli_anything/freecad/freecad_cli.py
+++ b/freecad/agent-harness/cli_anything/freecad/freecad_cli.py
@@ -171,8 +171,10 @@ output_fn = output
@click.group(invoke_without_command=True)
@click.option("--json", "use_json", is_flag=True, help="Output in JSON format.")
@click.option("--project", "-p", type=click.Path(), help="Load project file.")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx: click.Context, use_json: bool, project: Optional[str]) -> None:
+def cli(ctx: click.Context, use_json: bool, project: Optional[str], dry_run: bool) -> None:
"""cli-anything-freecad — CLI harness for FreeCAD 3D CAD modeler."""
global _json_output
_json_output = use_json
@@ -184,6 +186,8 @@ def cli(ctx: click.Context, use_json: bool, project: Optional[str]) -> None:
# Auto-save after one-shot commands when --project is used
def _auto_save():
+ if dry_run:
+ return
if sess._modified and sess.project_path and not _repl_mode:
sess.save_session()
diff --git a/gimp/agent-harness/cli_anything/gimp/gimp_cli.py b/gimp/agent-harness/cli_anything/gimp/gimp_cli.py
index 1ad650119..58031951b 100644
--- a/gimp/agent-harness/cli_anything/gimp/gimp_cli.py
+++ b/gimp/agent-harness/cli_anything/gimp/gimp_cli.py
@@ -118,8 +118,10 @@ def handle_error(func):
@click.option("--json", "use_json", is_flag=True, help="Output as JSON")
@click.option("--project", "project_path", type=str, default=None,
help="Path to .gimp-cli.json project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path):
+def cli(ctx, use_json, project_path, dry_run):
"""GIMP CLI — Stateful image editing from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -138,12 +140,18 @@ def cli(ctx, use_json, project_path):
@cli.result_callback()
-def auto_save_on_cli(result, **kwargs):
- """Auto-save project after CLI commands when --project is specified."""
- if not _repl_mode:
- sess = get_session()
- if sess.has_project() and sess._modified and sess.project_path:
- proj_mod.save_project(sess.get_project(), sess.project_path)
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
# ── Project Commands ─────────────────────────────────────────────
diff --git a/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.py b/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.py
index 89ff0a068..95a2e3ff1 100644
--- a/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.py
+++ b/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.py
@@ -40,6 +40,7 @@ _session: Optional[Session] = None
_json_output = False
_repl_mode = False
_auto_save = False
+_dry_run = False
def get_session() -> Session:
@@ -123,8 +124,10 @@ def handle_error(func):
help="Path to .inkscape-cli.json project file")
@click.option("-s", "--save", "auto_save", is_flag=True,
help="Auto-save project after each mutation command (one-shot mode)")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path, auto_save):
+def cli(ctx, use_json, project_path, auto_save, dry_run):
"""Inkscape CLI — Stateful vector graphics editing from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -132,9 +135,10 @@ def cli(ctx, use_json, project_path, auto_save):
Use -s/--save to automatically save changes after each mutation command.
This is useful in one-shot mode where each command runs in a new process.
"""
- global _json_output, _auto_save
+ global _json_output, _auto_save, _dry_run
_json_output = use_json
_auto_save = auto_save
+ _dry_run = dry_run
if project_path:
sess = get_session()
@@ -151,7 +155,9 @@ def cli(ctx, use_json, project_path, auto_save):
def _auto_save_callback():
"""Auto-save callback that runs after each command."""
- global _auto_save, _session
+ global _auto_save, _session, _dry_run
+ if _dry_run:
+ return
if _auto_save and _session and _session.has_project() and _session._modified:
# Don't auto-save if we're in REPL mode (user can explicitly save)
if not _repl_mode:
diff --git a/kdenlive/agent-harness/cli_anything/kdenlive/kdenlive_cli.py b/kdenlive/agent-harness/cli_anything/kdenlive/kdenlive_cli.py
index 7d63c2913..fa9738e00 100644
--- a/kdenlive/agent-harness/cli_anything/kdenlive/kdenlive_cli.py
+++ b/kdenlive/agent-harness/cli_anything/kdenlive/kdenlive_cli.py
@@ -125,8 +125,10 @@ def parse_time(value: str) -> float:
@click.option("--json", "use_json", is_flag=True, help="Output as JSON")
@click.option("--project", "project_path", type=str, default=None,
help="Path to .kdenlive-cli.json project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path):
+def cli(ctx, use_json, project_path, dry_run):
"""Kdenlive CLI — Stateful video editing from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -144,6 +146,21 @@ def cli(ctx, use_json, project_path):
ctx.invoke(repl, project_path=None)
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
+
+
# ── Project Commands ────────────────────────────────────────────
@cli.group()
def project():
diff --git a/krita/agent-harness/cli_anything/krita/krita_cli.py b/krita/agent-harness/cli_anything/krita/krita_cli.py
index b290a2d34..ed079425b 100644
--- a/krita/agent-harness/cli_anything/krita/krita_cli.py
+++ b/krita/agent-harness/cli_anything/krita/krita_cli.py
@@ -113,12 +113,25 @@ def _save_current(ctx: click.Context) -> None:
@click.group(invoke_without_command=True)
@click.option("--json", "use_json", is_flag=True, default=False, help="Output in JSON format.")
@click.option("--project", "-p", type=click.Path(), default=None, help="Path to project JSON file.")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project):
+def cli(ctx, use_json, project, dry_run):
"""cli-anything-krita: CLI harness for Krita digital painting."""
ctx.ensure_object(dict)
ctx.obj["json"] = use_json
ctx.obj["project"] = project
+
+ # Auto-save after one-shot commands when --project is used
+ is_oneshot = ctx.invoked_subcommand is not None
+
+ @ctx.call_on_close
+ def _auto_save():
+ if dry_run or not is_oneshot:
+ return
+ if _current_project and _current_project_path:
+ save_project(_current_project, _current_project_path)
+
if ctx.invoked_subcommand is None:
ctx.invoke(repl, project_path=project)
diff --git a/libreoffice/agent-harness/cli_anything/libreoffice/libreoffice_cli.py b/libreoffice/agent-harness/cli_anything/libreoffice/libreoffice_cli.py
index 3eaa71101..41d762677 100644
--- a/libreoffice/agent-harness/cli_anything/libreoffice/libreoffice_cli.py
+++ b/libreoffice/agent-harness/cli_anything/libreoffice/libreoffice_cli.py
@@ -117,8 +117,10 @@ def handle_error(func):
@click.option("--json", "use_json", is_flag=True, help="Output as JSON")
@click.option("--project", "project_path", type=str, default=None,
help="Path to .lo-cli.json project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path):
+def cli(ctx, use_json, project_path, dry_run):
"""LibreOffice CLI -- Stateful document editing from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -136,6 +138,21 @@ def cli(ctx, use_json, project_path):
ctx.invoke(repl, project_path=None)
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
+
+
# ── Document Commands ────────────────────────────────────────────
@cli.group()
def document():
diff --git a/mermaid/agent-harness/cli_anything/mermaid/mermaid_cli.py b/mermaid/agent-harness/cli_anything/mermaid/mermaid_cli.py
index 3f194f7b6..9ea4ca14d 100644
--- a/mermaid/agent-harness/cli_anything/mermaid/mermaid_cli.py
+++ b/mermaid/agent-harness/cli_anything/mermaid/mermaid_cli.py
@@ -40,8 +40,10 @@ def emit(data, message: str | None = None) -> None:
@click.group(invoke_without_command=True)
@click.option("--json", "json_mode", is_flag=True, help="Emit machine-readable JSON")
@click.option("--project", "project_path", default=None, help="Open a Mermaid project file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, json_mode: bool, project_path: str | None) -> None:
+def cli(ctx, json_mode: bool, project_path: str | None, dry_run: bool) -> None:
"""CLI harness for Mermaid Live Editor state files and renderer URLs."""
global _json_output, _session
_json_output = json_mode
@@ -51,6 +53,8 @@ def cli(ctx, json_mode: bool, project_path: str | None) -> None:
@ctx.call_on_close
def _auto_save() -> None:
+ if dry_run:
+ return
if project_path and _session and _session.is_open and _session.modified:
_session.save_project()
diff --git a/musescore/agent-harness/cli_anything/musescore/musescore_cli.py b/musescore/agent-harness/cli_anything/musescore/musescore_cli.py
index 4062d13fb..3707ab6f6 100644
--- a/musescore/agent-harness/cli_anything/musescore/musescore_cli.py
+++ b/musescore/agent-harness/cli_anything/musescore/musescore_cli.py
@@ -98,8 +98,10 @@ def handle_error(func):
@click.option("--json", "use_json", is_flag=True, help="Output as JSON")
@click.option("--project", "project_path", type=str, default=None,
help="Path to score file to open")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path):
+def cli(ctx, use_json, project_path, dry_run):
"""MuseScore CLI — Music notation from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -117,6 +119,21 @@ def cli(ctx, use_json, project_path):
ctx.invoke(repl)
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
+
+
# ── Project Commands ──────────────────────────────────────────────────
@cli.group()
diff --git a/obs-studio/agent-harness/cli_anything/obs_studio/obs_studio_cli.py b/obs-studio/agent-harness/cli_anything/obs_studio/obs_studio_cli.py
index fef144c61..490ffd422 100644
--- a/obs-studio/agent-harness/cli_anything/obs_studio/obs_studio_cli.py
+++ b/obs-studio/agent-harness/cli_anything/obs_studio/obs_studio_cli.py
@@ -118,8 +118,10 @@ def handle_error(func):
@click.option("--json", "use_json", is_flag=True, help="Output as JSON")
@click.option("--project", "project_path", type=str, default=None,
help="Path to OBS scene collection JSON file")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, use_json, project_path):
+def cli(ctx, use_json, project_path, dry_run):
"""OBS Studio CLI -- Stateful scene collection editing from the command line.
Run without a subcommand to enter interactive REPL mode.
@@ -137,6 +139,21 @@ def cli(ctx, use_json, project_path):
ctx.invoke(repl, project_path=None)
+def auto_save_on_exit(result, use_json, project_path, dry_run, **kwargs):
+ """Auto-save project after one-shot commands if state was modified."""
+ if _repl_mode:
+ return
+ if dry_run:
+ return
+ sess = get_session()
+ if sess.has_project() and sess._modified and sess.project_path:
+ try:
+ sess.save_session()
+ except Exception as e:
+ click.echo(f"Warning: Auto-save failed: {e}", err=True)
+
+
# -- Project Commands --------------------------------------------------------
@cli.group()
def project():
diff --git a/openscreen/agent-harness/cli_anything/openscreen/openscreen_cli.py b/openscreen/agent-harness/cli_anything/openscreen/openscreen_cli.py
index c893db712..4729275fb 100644
--- a/openscreen/agent-harness/cli_anything/openscreen/openscreen_cli.py
+++ b/openscreen/agent-harness/cli_anything/openscreen/openscreen_cli.py
@@ -26,6 +26,7 @@ _session: Optional[Session] = None
_json_output = False
_repl_mode = False
_auto_save = False
+_dry_run = False
# ── Output helpers ────────────────────────────────────────────────────────
@@ -115,8 +116,10 @@ def handle_error(func):
@click.option("--session", "session_id", default=None, help="Session ID to resume")
@click.option("--project", "project_path", default=None, help="Open project on start")
@click.option("-s", "--save", "auto_save", is_flag=True, help="Auto-save after mutations")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, json_mode, session_id, project_path, auto_save):
+def cli(ctx, json_mode, session_id, project_path, auto_save, dry_run):
"""Openscreen CLI — Screen recording editor.
Edit screen recordings via command line: zoom, speed, trim, crop,
@@ -124,9 +127,10 @@ def cli(ctx, json_mode, session_id, project_path, auto_save):
Run without a subcommand to enter REPL mode.
"""
- global _session, _json_output, _auto_save
+ global _session, _json_output, _auto_save, _dry_run
_json_output = json_mode
_auto_save = auto_save
+ _dry_run = dry_run
_session = Session(session_id)
if project_path:
@@ -212,7 +216,7 @@ def project_set(key, value):
pass
result = proj_mod.set_setting(_session, key, value)
output(result)
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
@@ -246,7 +250,7 @@ def zoom_add(start, end, depth, focus_x, focus_y, focus_mode):
_session, start, end, depth, focus_x, focus_y, focus_mode
)
output(result, "Zoom region added")
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
@@ -257,7 +261,7 @@ def zoom_remove(region_id):
"""Remove a zoom region by ID."""
result = tl_mod.remove_zoom_region(_session, region_id)
output(result)
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
@@ -286,7 +290,7 @@ def speed_add(start, end, spd):
"""Add a speed region."""
result = tl_mod.add_speed_region(_session, start, end, spd)
output(result, "Speed region added")
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
@@ -297,7 +301,7 @@ def speed_remove(region_id):
"""Remove a speed region by ID."""
result = tl_mod.remove_speed_region(_session, region_id)
output(result)
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
@@ -325,7 +329,7 @@ def trim_add(start, end):
"""Add a trim region (cuts this section out)."""
result = tl_mod.add_trim_region(_session, start, end)
output(result, "Trim region added")
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
@@ -364,7 +368,7 @@ def crop_set(x, y, w, h):
"""Set crop region (normalized 0-1 coordinates)."""
result = tl_mod.set_crop(_session, x, y, w, h)
output(result, "Crop updated")
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
@@ -400,7 +404,7 @@ def annotation_add_text(start, end, text, x, y, font_size, color, bg_color):
_session, start, end, text, x, y, font_size, color, bg_color
)
output(result, "Annotation added")
- if _auto_save and _session.project_path:
+ if _auto_save and not _dry_run and _session.project_path:
_session.save_project()
diff --git a/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.py b/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.py
index 2fa2f336a..39d06e7d4 100755
--- a/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.py
+++ b/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.py
@@ -115,6 +115,7 @@ def handle_error(func):
_repl_mode = False
_auto_save = False
+_dry_run = False
# ============================================================================
@@ -125,23 +126,26 @@ _auto_save = False
@click.option("--json", "json_mode", is_flag=True, help="Output in JSON format")
@click.option("--session", "session_id", default=None, help="Session ID to use/resume")
@click.option("--project", "project_path", default=None, help="Open a project file")
[email protected]("-s", "--save", "auto_save", is_flag=True,
[email protected]("-s", "--save", "auto_save", is_flag=True,
help="Auto-save project after each mutation command (one-shot mode)")
[email protected]("--dry-run", "dry_run", is_flag=True, default=False,
+ help="Run command without saving changes to disk")
@click.pass_context
-def cli(ctx, json_mode, session_id, project_path, auto_save):
+def cli(ctx, json_mode, session_id, project_path, auto_save, dry_run):
"""Shotcut CLI — Video editing from the command line.
A stateful CLI for manipulating Shotcut/MLT video projects.
Designed for AI agents and power users.
Run without a subcommand to enter interactive REPL mode.
-
+
Use -s/--save to automatically save changes after each mutation command.
This is useful in one-shot mode where each command runs in a new process.
"""
- global _json_output, _session, _auto_save
+ global _json_output, _session, _auto_save, _dry_run
_json_output = json_mode
_auto_save = auto_save
+ _dry_run = dry_run
if session_id:
_session = Session(session_id)
@@ -160,7 +164,9 @@ def cli(ctx, json_mode, session_id, project_path, auto_save):
def _auto_save_callback():
"""Auto-save callback that runs after each command."""
- global _auto_save, _session
+ global _auto_save, _session, _dry_run
+ if _dry_run:
+ return
if _auto_save and _session and _session.is_open and _session.is_modified:
# Don't auto-save if we're in REPL mode (user can explicitly save)
if not _repl_mode: