wm-screenshooter 2.1.0

A sophisticated cross-platform screenshot tool with timer support and organization features

WorkMaster ScreenShooter

Screenshooter is a sophisticated cross-platform screenshot TUI application with timer support and organisation features. This modular Python application helps freelancers document their work with automatic (or manual) screenshots and pairs this with contemporaneous notes and the ability to create and email a PDF report to their clients.

Why?

"As a freelance developer I love to code and help solve my clients' problems. Much of my work is hourly requiring me to keep accurate logs and notes. I created ScreenShooter to keep track of sessions, projects and notes for clients allowing me to focus on the fun parts of coding and not the admin."

• Conor Ryan - ScreenShooter Creator

Note: ScreenShooter supports macOS (Linux and Windows are supported but are under beta testing).

Features

• Application lives in your terminal and can be left in the background tracking time while you focus on work
• Screenshot capture can be done automatically at regular intervals or manually when the user requests them.
• Flexibility in screenshot capture all displays, specific display or a dedicated window.
• Produce captions (which appear under given screenshots) or notes for communicating ideas to clients
• Track project goals/tasks across sessions and include relevant progress in reports
• Ability to pause / resume when doing sensitive work
• Session based reporting system allows for flexibility and time management
• Built in client management features for sending reports and archiving finished projects
• Ability to generate and send reports to client after every session, day or when needed
• Upload reports to S3 bucket and generate link for clients to view
• CLI for quicker session start
• Backup functionality to back up settings, database, and screenshots directory
• Direct database backup command for timestamped raw SQLite .db snapshots before or outside schema migrations
• Workmaster sync: push local data (clients, projects, sessions, screenshots and notes) to the Workmaster remote dashboard and pull changes back (Find out more info here)
• Project goals and goal notes are included in Workmaster sync (pushed and pulled via the Workmaster API alongside sessions and screenshots).

Requirements

• Python 3.10 - 3.14
• macOS, Linux, or Windows
• For snippet drag-selection (w command):
  • PySide6-Essentials is optional and only required for GUI drag-selection.
• For desktop notifications (optional):
  • macOS: terminal-notifier (brew install terminal-notifier)
  • Linux: notify-send (usually pre-installed)
  • Windows: PowerShell (built-in)
• Email sending system (e.g. Brevo, SendGrid, Mailgun, etc.)
• S3 bucket (for remote report storage to make it easier to send reports to clients)
• Cloudflare KV (for custom link generation to make it easier to send reports to clients) (optional)

Installation

Option 1: Install from PyPI (Recommended)

pip install wm-screenshooter
screenshooter --version

To enable GUI snippet drag-selection (w) on top of the base install:

pip install "wm-screenshooter[snippet-gui]"

Option 2: Install from source (using uv)

1. Clone the repository and install the application using uv:

   git clone https://gitlab.com/workmaster/screenshooter.git
   cd screenshooter
   uv tool install .
   screenshooter --version
   

2. (Optional) enable GUI snippet drag-selection dependency:

   uv sync --extra snippet-gui
   

(Optional) Install notification support

Notification support is optional and will be disabled if not installed.

macOS:

brew install terminal-notifier # macOS

Linux: (Debian/Ubuntu)

sudo apt install libnotify-bin  # Debian/Ubuntu

Windows:

Not required as already built in.

Usage

Screenshooter can be used either via the command-line interface or via the interactive menu. Until you have created a client and project, you will need to use the interactive menu to set up your project and client.

Interactive Menu (first time use)

Below is the general flow for performing some of the common actions in the ScreenShooter program. Below will

How to take screenshots

TLDR; Skip to step 3 if you have already created a client and project.

1. On the main ScreenShooter screen press option 1.

2. As this is your first time using the application you will be prompted to create a client and a project. Do the following:

   • Enter the name of your client (no spaces) - eg: "Testing"
   • Press n for no to create a custom directory name for your client
   • Enter the Company Name - eg: "Testing Ltd"
   • Contact Name - eg: "John Doe"
   • Contact Email - eg: "[e-mail]"
   • Screenshot delivery method [local/email/cloud] (enter):
   • Notification preferences [all/important/none] (enter):
   • Reporting frequency [daily/weekly/monthly/none] (enter):
   • PDF security [none/password] (enter):
   • PDF page size [A4/letter] (enter):
   • Press enter to save the client information

3. You will now be asked to create a project. Do the following:

   • Enter the name of your project (no spaces) - eg: "BigProject"

4. (Start of Session)

   • Choose the display mode you want to use (press enter to use all):
   • Enter the timer duration in minutes - eg: 15
   • Type a note to start the session - eg: "Started working on BigProject"
   • Press enter to start the session

   A Countdown will start to take the first screenshot. (10 seconds).

   • The session is now running, the timer is counting down to the next screenshot.

   • Refer to the in-session commands below on how to interact with the session.

   • When you are finished with the session you can press 'q' to quit and take a final screenshot.

In-session commands

'n' - to add a note to the log
'g' - to manage project goals
'c' - to add a caption to the last screenshot
's' - to take a manual screenshot now and reset timer
'o' - to open the last screenshot in Preview
'q' - to quit and take final screenshot
't' - to change the timer duration
'd' - to change the display mode
'p' - to pause the session for sensitive activities
'm' - to switch to manual mode (no timer)
'r' - to archive the last action (screenshot or note)
'e' - to list the last 5 actions
'l' - to open the current session log in TextEdit
'i' - to show time in session, today, and project total
'h' - for help
'z' - to cancel active countdowns 

Project goals

During a screenshot session, press g to open the project goals menu. Goals persist across every session in the current project. From the menu you can add goals, add progress notes, complete goals with an optional note, archive goals that are no longer applicable, and review current or recently closed goals. Relevant goal updates are included in session, day, and project reports when the database is enabled.

CLI Command Structure

ScreenShooter uses a command-line interface with nested commands:

screenshooter                                   # Interactive menu
screenshooter client                            # List all clients
screenshooter client "ClientName"               # Manage specific client
screenshooter client "ClientName" projects      # List projects
screenshooter shoot --client "Name" --project "Project" [options]
screenshooter report                            # Interactive report generator
screenshooter --debug                           # Interactive menu; reports/backups use debug logs
screenshooter --debug report                    # Interactive report generator with debug logs
screenshooter report generate --client "Name" --project "Project"
screenshooter --debug report generate --client "Name" --project "Project"
screenshooter open logs|config                  # Open logs or config directories
screenshooter settings                          # Manage settings
screenshooter sync                              # Workmaster sync menu
screenshooter sync setup                        # Configure Workmaster sync
screenshooter sync status                       # Show Workmaster sync status
screenshooter sync run                          # Run one Workmaster sync cycle
screenshooter sync run --debug                  # Show sanitized sync request/response details
screenshooter sync set --upload-images          # Upload screenshots to Workmaster R2
screenshooter sync set --image-upload-workers 8 # Set parallel image upload workers
screenshooter upgrade                           # Manage upgrade checks and notifications
screenshooter backup <settings|db|all> [--outputdir PATH]  # Create backups
screenshooter backup all --debug               # Write full structured backup event details
screenshooter --debug backup all               # Same backup debug logging via global flag
screenshooter db                                # Database management menu
screenshooter db backup                         # Create a timestamped raw SQLite DB backup
screenshooter help                              # Show help information

For more information on the commands and options available, run screenshooter command --help for more information.

Directory Structure and Screenshot Storage

Screenshots are organized in the following structure:

~/WorkMaster_Screenshooter/
└── CLIENT_NAME/
    ├── client.json     # Client information and preferences
    └── PROJECT_NAME/
        ├── project.json
        ├── PROJECT_NAME_log.txt
        ├── reports/
        │   └── PROJECT_NAME_Report_YYYYMMDD_HHMMSS.pdf
        └── sessions/
            └── YYYY-MM-DD_HH-MM-SS/
                ├── session.log
                ├── session.json
                └── screenshots/
                    └── PROJECT_NAME_YYYY-MM-DD_HH-MM-SS_*.jpg

Above is the general structure of the application.

Notes

Email Support and Remote Report Storage

If you want to send screenshot reports to your client via email, configure the email settings in the settings menu. ScreenShooter supports:

• SMTP for traditional authenticated relay delivery
• Cloudflare Email Sending via Cloudflare's REST API

SMTP remains the default provider for backward compatibility.

Brevo is still a reasonable SMTP option with a generous free tier and simple setup. Cloudflare Email Sending is also supported if you have access to that product.

Many providers limit large attachments. To handle that, ScreenShooter can upload the report to an S3/R2 bucket and email a download link instead of attaching the PDF directly.

You can set up an S3 bucket and configure ScreenShooter to use it via the s3 setting in the settings menu. The S3 bucket will be used to store the screenshot reports and the link to the report will be generated and sent to your client via email.

For report delivery troubleshooting, run screenshooter --debug before generating and emailing a report. In report debug mode, the TUI shows the same report email and S3/R2 log events that are written during delivery, including upload details, link generation, Cloudflare KV output, and email transport status. Secrets such as SMTP passwords, S3 secret keys, Cloudflare API tokens, and authorization headers should not be printed.

Updates

Checks for new versions of ScreenShooter are checked automatically every 7 days and can be checked manually with screenshooter upgrade check.

At this stage updates are not automatically installed. The update notification will ask you to update via pip / git.

Two update channels are available:

• release (default): checks GitLab releases for the latest mainline version available and informs the user every 7 days as configured.
• dev: performs commit-based checks against the configured branch head on the official upstream GitLab project on every execution. For more information on the dev branch, see the DEVELOPMENT file.

You can also skip or pin specific versions of ScreenShooter to prevent notifications for these or future versions (release channel only).

screenshooter upgrade check # Check for updates
screenshooter upgrade status # Show current channel/branch behavior
screenshooter upgrade channel <release|dev> # Set update channel
screenshooter upgrade branch <branch-name> # Set dev channel branch target
screenshooter upgrade settings --enable --frequency 7 # Configure checks
screenshooter upgrade skip <version> # Skip notifications for a specific version
screenshooter upgrade pin <version> # Pin to a specific version (release channel only)
screenshooter upgrade unpin # Remove pinned version (release channel only)

The upgrade itself is not automatically installed and requires you to manually download the latest version and install it.

If installing from PyPI:

pip install --upgrade wm-screenshooter
screenshooter --version

If installing from GitLab you can use the following command to install the latest version:

git pull
uv tool install .
screenshooter --version

Updates to the Database

When an existing database has pending schema migrations, ScreenShooter prompts before applying database updates, creates a timestamped raw SQLite backup, and exits without applying migrations if the user declines. Direct DB backups are saved under ~/.config/screenshooter/db_migration_backups/.

Speed of Uploads (reports / backups)

The speed of uploads to remote S3/R2 buckets can be configured if needed to ensure maximum concurrency. A default of 8 threads has been chosen. It is not recommended to change this setting as how much benefit you receive from this determines on a combination of your CPU speed and available upload speed from your internet provider.

That said if you wish to, the setting can be found in the s3 settings.

Report and Backup Troubleshooting

Use the --debug option when troubleshooting report generation, report S3/R2 upload links, report email delivery, or backup event details. screenshooter --debug carries into reports and backups launched from the interactive menu, and the direct backup command also supports screenshooter backup all --debug. Sync has its own scoped debug flag: screenshooter sync run --debug.

Contributing

For contributor and branch workflow guidance (including dev/release upgrade channels), see docs/DEVELOPMENT.md.

Contributors should generally work from forks and open merge requests from fork branches rather than being given direct push access to the main repository. Dev-channel upgrade checks compare against the official upstream GitLab project, not arbitrary contributor forks.

Workmaster Sync

ScreenShooter can sync your local data to the WorkMaster dashboard, allowing you to view clients, projects, sessions, screenshots and notes from any browser.

Sync uses an incremental push/pull approach:

• Push sends any locally created or updated records to Workmaster since the last sync.
• Pull applies any changes made in the Workmaster dashboard back to the local database.
• Records are matched between local and remote using a remote_uuid — local integer IDs are never changed.

To enable sync, run:

screenshooter sync setup

Create a long-lived Screenshooter API key in Workmaster at /dash/settings/api-keys and paste it into the setup prompt.

Use screenshooter sync status to review the current configuration and local checkpoints. Use screenshooter sync run to trigger a sync cycle, or screenshooter sync run --debug to print sanitized request and response details while troubleshooting. Pushes are sent in small batches so Workmaster can apply the data and write its change log within D1 query limits. The device_id is generated automatically on first sync, persisted to your settings, and sent to Workmaster as X-WorkMaster-Device-Id.

Running screenshooter sync without a subcommand opens a numbered Workmaster Sync menu. The menu header shows the configured Workmaster URL, compact sync settings, auto-sync state, and last push/pull checkpoints. From there you can run sync, view sync status, edit sync settings, open the logs directory, open the Workmaster API key page, or clear the stored API key. The prompt accepts b to go back.

Automatic sync is optional and off by default. screenshooter sync setup can enable independent auto-sync hooks for interactive app startup, after a screenshot session ends, and interactive app exit. Startup and exit auto-sync only apply to the bare interactive screenshooter menu; after-session auto-sync also applies when using screenshooter shoot. Automatic sync failures are non-blocking: ScreenShooter shows a concise warning and continues the current flow. Use screenshooter sync set --auto-on-startup/--no-auto-on-startup, --auto-after-session/--no-auto-after-session, --auto-on-exit/--no-auto-on-exit, and --auto-quiet/--no-auto-quiet for non-interactive configuration.

Screenshot image upload to Workmaster R2 is optional. Enable it in screenshooter sync setup or with screenshooter sync set --upload-images, then run screenshooter sync run. Image uploads run after metadata push/pull completes, and use parallel workers so large screenshot batches do not upload one file at a time. The default is 8 workers; the setup flow prompts for this when image upload is enabled, and scripts can change it with screenshooter sync set --image-upload-workers 12. Use 1 worker for serial troubleshooting, try 12 or 16 on fast connections, and reduce to 4 if failures or throttling increase. Values are limited to 1-32.

Interactive screenshooter sync run shows aggregate upload progress and measured transfer speed during image upload. The speed is observed from bytes uploaded over time, not an assumed or configured network speed. Parallel upload helps most with many screenshots, especially when individual files are latency-bound, but it does not guarantee a workers-times speedup because results also depend on file sizes, local disk speed, Cloudflare R2 behavior, and Workmaster prepare/complete API latency. screenshooter sync run --debug suppresses the progress bar and prints sanitized per-file upload details instead. Auto-sync also suppresses the progress bar.

Who Made This?

ScreenShooter is being developed by @conorjwryan as a part of the WorkMaster project. WorkMaster is a platform for freelancers to manage their work and clients. ScreenShooter is its companion application for capturing screenshots of their work when requested by clients.

The WorkMaster site is under closed development at the moment and is not ready for public use. More information will be available soon.

In the meantime, please checkout Conor's website and his GitLab for more of his projects.