Command-line reference

Sweepy installs as one command, sweepy. Type it and press Enter. Add a flag when the command needs more than the defaults. Every profile, sweep, and report starts here.

Terminal

sweepy

Alex uses two of these commands each morning. First --run sweeps with the last saved profile. Then --logs reports what happened when a run looks wrong.

note

Run every command from inside your sweepy folder. If you closed your terminal since the last step, reopen it and run cd sweepy first.

Command reference

Run sweepy with no flag to open the wizard's search launchpad. The tables below group every flag by the job it performs.

Command form

Run pip install -e . once in the sweepy folder. The pages below write the short form because that command registers it. If your shell can't find sweepy, reopen the terminal or run python swee.py instead.

Sweeps and profiles

Flag	What it does
--run	Runs a sweep with your last saved profile.
--profile <path>	Runs a sweep from a YAML profile.
--setup	Opens the search launchpad for searches and profile setup.
--non-interactive	Builds or updates a profile from flags instead of prompts. Pair it with --setup.

One-run overrides

Flag	What it does
--no-dedupe	Keeps duplicate postings from separate boards for one sweep.
--include-seen	Reports postings from an earlier sweep too.
--reset-history	Forgets the postings already reported for the profile.

Documents

Flag	What it does
--docx <path>	Converts a DOCX file to PDF, then exits.
--convert <path>	Converts a supported document to PDF beside the source file, then exits.

Job search engines

Flag	What it does
--list-engines	Lists every engine, the boards it reads, and its install state.
--install-engines [names]	Downloads every optional engine, or only the engines you name.
--allow-engine-conflicts	Installs an engine whose pin conflicts with an installed one, skipping that pin. Pair it with --install-engines.

Updates and version

Flag	What it does
--update	Pulls the newest Sweepy code and reinstalls dependencies.
--check-update	Reports whether a newer Sweepy version exists.
--version	Shows the engine version and its dependencies.

Logging

Flag	What it does
--debug	Turns on debug logging under logs/.
--log-dir <dir>	Moves the debug log folder.
--logs	Prints the most recent debug log entries.

Headless setup values

These flags fill a profile when you add --setup. Each value needs its matching flag, and --name, --titles, --location, and --resume stay required unless the profile supplies them.

Flag	What it does
--sources <names>	Enables these engines, comma-separated.
--jobspy-sites <sites>	Sets JobSpy boards, comma-separated.
--hirehunt-sources <sources>	Sets HireHunt sources, comma-separated.
--jobdrop-sites <sites>	Sets JobDrop boards, comma-separated.
--openroles-companies <slugs>	Sets OpenRoles company slugs, comma-separated.
--apify-actor <actor>	Sets the Apify actor ID.
--timeout <seconds>	Sets the per-source timeout.
--cache-ttl <seconds>	Sets the discovery cache lifetime.
--no-cache	Disables the discovery cache.
--history-days <days>	Sets the days before a reported posting can appear again.
--no-history	Reports every posting on every run.
--job-tracking / --no-job-tracking	Turns the CSV job-tracking columns on or off.
--name <name>	Sets the name on the profile.
--titles <titles>	Sets target titles, comma-separated.
--location <location>	Sets the target location.
--resume <path>	Sets the resume path.

Sweepy handles --logs, --version, --update, --check-update, --list-engines, and --install-engines first, then converts documents. --setup follows, and a sweep runs last. Run one job per command.

Run your last profile with --run

Save a profile once, then sweep with one short command. Sweepy stores the last profile you saved in profiles/.last_profile and reuses it.

Terminal

sweepy --run

The command resolves a profile in this order:

1. The path in profiles/.last_profile.
2. The newest profile in profiles/.
3. profiles/custom_profile.yaml, then profiles/paralegal_nyc.yaml, then config.sample.yaml.

When none of those exist, Sweepy reports an error and points you at --setup.

Build a profile with --setup

The wizard opens the search launchpad and writes a YAML profile for you.

Terminal

sweepy --setup

Launchpad tile	What it does
Launch Sweep	Runs a sweep with the profile you opened. The status line warns you until you open a profile.
Load Profile	Lets you choose a saved profile to use for the next sweep.
Sweepy's Toolbox	Opens the toolbox entries listed below.
Build Profile	Asks plain-English questions, then saves a new profile.
Sweep Settings	Changes keyword weight, card limits, report style, history behavior, and the job-tracking columns in the CSV.
Exit Sweepy	Saves your changes and returns to the shell.

Sweepy's Toolbox holds the remaining actions:

Toolbox entry	What it does
Edit an existing profile	Loads a profile from profiles/ and lets you change it, including a toggle for the job-tracking columns.
Manage job engines	Turns engines on or off and edits their settings.
Download job engines	Installs optional engines after you confirm.
Add or edit aggregators	Toggles feeds and manages custom aggregators.
Toggle debug logging	Flips the profile's debug value.
Show help	Prints guidance for the wizard.
Show recent logs	Prints the newest debug log entries.
Convert a document to PDF (bonus)	Converts a DOCX, DOC, TXT, MD, or PDF file and returns to the toolbox.
Update Sweepy	Pulls the newest code and reinstalls dependencies.
Exit	Closes the wizard from the toolbox.

Re-run the wizard any time to create another profile or edit an existing one. It never deletes your old profiles. The Setting up Sweepy page walks through every question.

Convert a document to PDF (bonus)

Sweepy's Toolbox converts a document even without a profile. Choose Convert a document to PDF (bonus), then give Sweepy a path.

Input	What Sweepy does
.docx	Rebuilds clean text with python-docx and reportlab, then falls back to Microsoft Word.
.doc	Renders through Microsoft Word, which needs the docx2pdf package.
.txt, .md	Renders the text with headings and bullets.
.pdf	Passes the file through, or copies it to the output path you name.

Sweepy prints a warning for a bad path and reopens the prompt. A typo returns you to the wizard.

Jump straight to a profile

Add --profile to open one profile for editing without the launchpad:

Terminal

sweepy --setup --profile profiles/paralegal_nyc.yaml

The wizard seeds the review screen with that file's current values.

Build a profile without prompts

Script a profile when you need the same setup on every machine. Add --setup --non-interactive and pass each value as a flag:

Terminal

sweepy --setup --non-interactive `
  --name "Alex Rivera" `
  --titles "Technical Writer,UX Writer" `
  --location "New York, NY" `
  --resume C:\Users\Alex\sweepy\resume.pdf `
  --sources jobspy,openroles `
  --openroles-companies figma,stripe,notion `
  --timeout 120 --no-cache

Sweepy checks every enabled engine before it writes the file. A missing value, such as OpenRoles company slugs, prints Error: and exits with code 1. Without --profile, Sweepy builds the filename from your name and first title, so Alex's profile saves to profiles/alex_rivera_technical_writer.yaml. Add --profile <path> to update an existing file instead.

Sweepy updates

Pull the newest code and reinstall dependencies with:

Terminal

sweepy --update

Sweepy fetches the origin remote, fast-forwards the current branch, and runs python -m pip install -r requirements.txt. It refuses to run when tracked files hold uncommitted changes, so it never discards local edits. Prefer the read-only check to see whether an update exists:

Terminal

sweepy --check-update

Update Sweepy in Sweepy's Toolbox runs the same update.

Manage job search engines

List every engine, the boards it reads, and its install state:

Terminal

sweepy --list-engines

Download the optional engines:

Terminal

sweepy --install-engines all

The all set skips JobDrop while JobSpy holds its conflicting pin. Install JobDrop on its own with --allow-engine-conflicts:

Terminal

sweepy --install-engines jobdrop --allow-engine-conflicts

Installing an engine leaves it switched off. Add it to sources.enabled in a profile or pass --sources during a headless setup. The command exits with code 1 when an install fails. Optional engines covers each engine.

Run a sweep with --profile

Keep one profile per city or role type, then point --profile at the one you want. Sweepy does the rest.

Terminal

sweepy --profile profiles/paralegal_nyc.yaml

Swap in your own filename. Prefer --run when you want Sweepy to reuse the last profile you saved.

tip

Store one profile per city or role type. Change one filename to switch between searches.

Override one run

--run and --profile accept three overrides. Each one applies to that command and leaves the profile untouched.

Terminal

sweepy --run --no-dedupe
sweepy --run --include-seen
sweepy --run --reset-history

--no-dedupe keeps every board's listing when two boards post the same role. A sweep reports new postings only, and history.retention_days in the profile sets the window at four days by default. --include-seen reports the hidden postings too. Run --reset-history alone to clear that history and exit without a sweep.

What happens during a sweep

Every run follows the same five stages, in the same order.

Stage	What happens
1. Profile loading	Reads your YAML file and checks the settings.
2. Discovery	Runs the scrapers across your enabled platforms and collects postings.
3. Validation	Removes dead links and catches soft 404 redirects. Postings the check can't verify stay in the run.
4. Scoring	Parses your resume PDF or DOCX for term overlap, then writes an Application Tip for each role.
5. Generation	Builds the date-stamped PDF, CSV, and JSON files. Add png to your export formats for page images.

The terminal prints each stage as [1/5] through [5/5] while it works. Running your first sweep shows the full output.

Convert a DOCX to PDF with --docx

Give --docx a Word file. Sweepy converts it, saves the PDF, and exits.

Terminal

sweepy --docx path/to/resume.docx

Sweepy then prompts for a PDF destination.

Terminal output

Where should the PDF go? (leave blank to save next to the DOCX):

Press Enter with an empty answer, and the PDF lands beside the DOCX with the same base name. Type a full path instead to save it somewhere else. Either way, Sweepy prints PDF saved: and the final location.

note

Sweepy rebuilds the PDF from the DOCX text first. When your machine has Microsoft Word, Sweepy falls back to docx2pdf for a closer visual match.

Convert any document with --convert

--convert runs without prompts and writes the PDF beside the original file. Point it at a .docx, .doc, .txt, .md, or .pdf file.

Terminal

sweepy --convert path/to/resume.docx

Terminal output

PDF saved: C:\Users\Alex\sweepy\resume.pdf

The output keeps the source name and swaps the extension, so notes.md becomes notes.pdf in the same folder. A .pdf source already sits in place, so Sweepy reports This file is already a PDF: and leaves the file in place.

Input	What Sweepy does
.docx	Rebuilds clean text with python-docx and reportlab, then falls back to Microsoft Word.
.doc	Renders through Microsoft Word, which needs the docx2pdf package.
.txt, .md	Renders the text with headings and bullets.
.pdf	Leaves the file untouched and reports its path.

A missing or unsupported file prints Error: and exits with code 1. That makes the command safe inside scripts and scheduled jobs.

Once the PDF exists, point resume.path in your profile at it and run a sweep.

Check your version with --version

Use this command to confirm the engine and its libraries installed correctly.

Terminal

sweepy --version

Terminal output

Sweepy v3.0.0
Python 3.13.1 | pymupdf 1.28.2 | reportlab 5.0.1
Ready to sweep.

If pymupdf or reportlab reads MISSING, reinstall your dependencies. Installation covers that step.

Turn on debug logging

Debug logs record what the engine does, step by step. Switch them on with a flag, a profile setting, or an environment variable.

Method	Where you set it	How long it lasts
--debug flag	Add it to your terminal command.	Lasts for that run only.
debug: true	Add it to your YAML profile.	Every run until you remove it.
SWEEPY_DEBUG=1	Set it as an environment variable.	Every run until you close the terminal.

Add the flag to any sweep:

Terminal

sweepy --debug --profile profiles/paralegal_nyc.yaml

Or switch logging on permanently inside your profile:

profiles/paralegal_nyc.yaml

# Write a rotating debug log under logs/ on every run.
debug: true

Or set the environment variable instead:

Terminal

$env:SWEEPY_DEBUG = "1"
sweepy --profile profiles/paralegal_nyc.yaml

On macOS or Linux, swap the first line for export SWEEPY_DEBUG=1.

Sweepy writes logs to logs/ inside the app folder. Send them elsewhere with --log-dir:

Terminal

sweepy --debug --log-dir C:\Users\Alex\sweepy-logs --profile profiles/paralegal_nyc.yaml

To read the most recent entries without opening a file, run:

Terminal

sweepy --logs

note

The --logs command prints No debug logs found. Run Sweepy with --debug to enable logging. until a debug log exists.

Schedule daily runs

Hiring teams post new roles all week. Run the same command each morning, and you catch those postings early.

Terminal

sweepy --profile profiles/paralegal_nyc.yaml

A run with new postings writes report files. Sweepy puts the profile, the date, and the time into each report filename, as in paralegal_nyc_2026-10-08-081500.pdf and paralegal_nyc_2026-10-08-081500.csv. Sweepy reads the time in Coordinated Universal Time, so the stamp can differ from your local clock. The stamp keeps one run from overwriting another, so results holds a full history of your search.

Sweeps report new postings only, and Sweepy remembers each posting it reports for four days by default. When a morning turns up nothing new, the run prints No new postings since your last sweep and doesn't write report files. The same happens when every discovered link has expired.

Schedule on Windows

1. Open Task Scheduler from the Start menu.
2. Choose Create Basic Task and name it something like Sweepy morning sweep.
3. Pick Daily, then choose a start time such as 8:00 AM.
4. For the action, choose Start a program.
5. Set Program/script to your Python executable. Run (Get-Command python).Source in PowerShell to print that path.
6. Set Add arguments to the full path of swee.py plus the profile: "C:\Users\Alex\sweepy\swee.py" --profile profiles\paralegal_nyc.yaml.
7. Set Start in to your sweepy folder. The engine finds profiles and writes results from that folder.

Schedule on macOS and Linux

1. Open your crontab with crontab -e.
2. Add a line that runs the sweep at 8:00 AM every day, in the machine's time zone.

Terminal

0 8 * * * cd /path/to/sweepy && python3 swee.py --profile profiles/paralegal_nyc.yaml

The cd part matters. The engine reads profiles and writes results relative to the folder you launch it from. Use the python3 that installed Sweepy's packages. Test it with python3 -c "import swee".

caution

A scheduled run starts without a terminal window, so shell settings from earlier sessions don't apply. Run the command by hand once. Confirm it works before you schedule it.