Automation surfaces
BetterScreenShot v0.5.47 and above provides two local automation entry points:
- A command-line companion for the signed-in Windows user.
- The
betterscreenshot://URI protocol for supported commands.
These surfaces can start validated BetterScreenShot workflows. They are not a remote web API and do not provide unattended Google Drive upload.
Security model
The command-line companion communicates with the running app through an authenticated per-user Windows named pipe. The app validates the command name, parameter names, parameter types, values, paths, and execution state before running anything.
Externally initiated URI capture commands require visible approval. A website or document should not be able to silently start screen capture simply because it can open a custom URI.
Supported workflow groups
The implementation includes commands for areas such as:
- Area capture.
- Window capture.
- Display capture.
- Recording.
- OCR.
- Floating references.
- History actions.
- Export.
- Settings and desktop controls.
- Quick Access actions.
Exact command names and parameters can change between versions. Use the help output from the command-line companion installed with your BetterScreenShot version instead of copying an old command list from another machine.
Start safely
- Install BetterScreenShot from its normal package.
- Start the desktop app normally.
- Confirm that no capture, recording, export, recovery, or settings operation is already active.
- Open a normal command prompt as the same Windows user.
- Run the companion's help command.
- Test with a harmless area capture.
- Confirm the result in BetterScreenShot and History.
- Add one parameter at a time.
Do not run the automation companion as a different Windows account or elevated service expecting it to control another user's desktop session.
URI approval
When another application opens a betterscreenshot:// capture request, BetterScreenShot presents the request for approval where the command requires it.
Before approving:
- Confirm which application, page, shortcut, or document opened the link.
- Review the requested action.
- Close private windows that should not be captured.
- Reject unexpected or repeated prompts.
File paths and export
Use normal absolute Windows paths when a command requires a source or destination. The app validates supported path and extension combinations.
- Do not target BetterScreenShot application-data internals.
- Do not overwrite an important file while testing.
- Confirm that the destination folder exists and is writable.
- Use a dedicated test folder first.
- Check the actual result before treating process exit as proof of a correct capture.
Recording commands
Automation can start supported recording workflows, but Windows permissions, source availability, active operation guards, audio devices, camera state, and capture exclusions still apply.
For unattended or repeatable recording tests:
- Use non-sensitive test content.
- Confirm the exact source.
- Disable unnecessary microphone, camera, or printable-key overlays.
- Keep a visible stop path.
- Verify finalization and History before running another recording.
OCR commands
OCR automation still processes the supplied image locally. Recognition accuracy depends on source resolution, crop, contrast, language data, and layout.
Do not automatically send OCR output into a privileged command, password field, financial workflow, or external publication without validation.
Google Drive is not an automation command
Google Drive upload is deliberately unavailable through the automation protocol. The legacy upload parameter is rejected.
Sharing requires a visible user choice inside BetterScreenShot because it can:
- Render current edits.
- Upload a file to an external service.
- Create an anyone-with-the-link permission.
- Copy a public link.
Use the Google Drive Sharing Guide for the interactive workflow.
Exit codes and verification
Treat an exit code or acknowledgment as the automation result, not proof that every visual detail is correct.
After a capture or export:
- Confirm the expected file exists.
- Open it and inspect the pixels or media.
- Confirm the source, bounds, cursor, scale, format, audio, and duration.
- Check History when the active profile should create an item.
- Preserve error text and the BetterScreenShot version when reporting a problem.
Automation request is rejected
Possible causes include:
- Unknown command.
- Unknown or deprecated parameter.
- Invalid value or file type.
- Missing required parameter.
- A path outside an allowed workflow.
- An active capture, recording, export, or recovery operation.
- A command that requires user approval.
- A command deliberately unavailable to automation, including Google Drive upload.
Run the installed companion's help output and simplify the command to the smallest valid test.
Privacy guidance
Automation can capture sensitive screens more quickly than a manual workflow. Keep scripts local, review them before running, and avoid embedding passwords, tokens, account numbers, confidential paths, or personal data.
Do not distribute an automation URI that starts a capture without explaining what it will request.