cli.md

title	Command-Line Reference
status	reviewed
last_verified	2026-10-28
verified_against	src/auto_apply/main.py argument parser
audience	everyone

Command-Line Reference

Two entry points are declared and behave identically:

python -m auto_apply      # module entry
auto-apply                # console script, available after install

Flags

Flag	Argument	Effect
--cli	—	Run the terminal interface instead of the GUI
--debug	—	Verbose debug logging
--check-config	—	Print an environment and capability summary — including the resolved motion (pointer/scroll) profile and its effective values — then exit
--profile	NAME_OR_PATH	Use a named profile or a profile file for this run
--portable	—	Store all data in ./data/ relative to the working directory
--seed	N	Deterministic mode. Identical configuration produces identical execution traces
--export-research	—	Export collected research signals and exit, without running a session
--export-format	csv | ndjson | parquet	Output format for --export-research. Default csv
--research-summary	—	Print what the discovery research tables hold, then exit. Read-only; starts no session
--replay	folder	Re-run text extraction and the research detectors over a folder of kept page copies (*.warc.gz) — no browser, network or research key — and write replay.jsonl, manifest.json and environment.json. Same folder + same AA version = same bytes on any machine. See Reproducibility. Exits 0, or 2 when the folder does not exist
--replay-out	folder	Where --replay writes. Default: reports/replay_<corpus digest> in AA's data folder
--research	—	Open the interactive research screen (see whether research is on, read the consent text, agree, withdraw with optional export-then-delete, page copies, export), then exit. Needs no profile; starts no session
--label	—	Label saved pages and log the applications you make by hand. See Labelling
--search	—	Open the interactive search builder (compose a verified engine, platform or company search), then exit. No session, no automation. Scripted flags take precedence
--search-surface	NAME	Scripted builder: search surface (google, bing, duckduckgo, indeed, linkedin; default google)
--search-platform	NAME	Scripted builder: a hiring platform — builds a site:-restricted engine search
--search-company	URL	Scripted builder: a company careers-page URL — scopes the search to that tenant
--search-terms	TEXT	Exact words or phrases, comma separated
--search-any-of	TEXT	Alternatives, comma separated (where the surface supports them)
--search-exclude	TEXT	Words to exclude, comma separated
--search-in-title	TEXT	Words that must appear in the title
--search-location	TEXT	Location, for surfaces that take one
--search-option	KEY=VALUE	A surface option (repeatable), e.g. date=day
--search-open	—	Open the built link in your browser (remembers the query)
--search-keep	—	Remember the built query without opening it
--search-recent	—	List your recent built searches, then exit
--search-clear-recent	—	Forget every remembered search, then exit
--encrypt-profile	—	Encrypt the current plaintext profile into a .vault file behind a master password
--platforms	NAMES	Hiring platforms for automated site-restricted search this session, comma-separated (e.g. --platforms jobvite). none disables platform targeting. Only measured or vendor-verified platforms are ever planned
--print-plan	—	Print what a session would search (engines, platforms, queries, budget) and exit. Offline; starts no session and no browser. Composes with --seed and --platforms

Building a search

python -m auto_apply --search
python -m auto_apply --search-platform workday --search-terms "Software Engineer"
python -m auto_apply --search-company "https://holisticai.bamboohr.com/careers/59" --search-open
python -m auto_apply --search-recent

Composes verified engine, platform (site:-restricted) and tenant-scoped company searches. What a surface cannot express is refused in plain words — never silently dropped. Copy, open and keep are the only actions that remember a query (five, deduplicated, in your data home; --search-clear-recent forgets them).

Previewing the plan

python -m auto_apply --print-plan
python -m auto_apply --print-plan --platforms jobvite
python -m auto_apply --print-plan --seed 42

Prints what a session would search — the engines, the platforms, the composed queries and the session budget — then exits. Offline: no session, no browser, no network. With no platforms chosen it shows the generic searches the session will actually run. A profile must exist; without one the command says so and exits non-zero. --platforms also applies to a real CLI session (python -m auto_apply --cli --platforms jobvite); none disables platform targeting for that session.

Flags parsed before anything else

--portable and --seed are read by a pre-parser that runs before any auto_apply module is imported.

This is not tidiness. domain/config.py computes the data directories at import time, so AA_DATA_DIR must be set before that import happens or portable mode silently writes to the wrong place. The seed has the same constraint: it must be in the environment before any component reads it.

Both flags are also declared on the main parser so they appear in --help.

Determinism

python -m auto_apply --cli --seed 42

--seed N derives an independent, reproducible random stream per namespace via SHA-256(seed:namespace). Runs with the same seed and the same configuration make the same choices (provider order, timing). That does not make a live session's research output repeatable — the sites change between visits; the repeatable research step is --replay.

Without --seed, AA uses an unseeded generator. That is the correct default for real use — a fixed seed makes your behaviour predictable to the sites you visit.

Portable mode

cd /media/usb/autoapply
python -m auto_apply --portable

Everything AA writes — profiles, database, logs, reports, caches — goes to ./data/ next to the working directory. Equivalent to setting AA_DATA_DIR yourself.

[PARTIAL] — portable mode runs, and launch_portable.sh has known containment defects, including not setting SE_CACHE_PATH, which lets Selenium Manager write a driver to the host's cache. See STATUS.md before relying on "no traces on the host".

Exporting research data

python -m auto_apply --export-research --export-format ndjson

Exits without running a session. parquet requires the research extra. Exports only what you consented to collect; if you never opted in, the export is empty. Format details are in research_module/data_format.md.

Encrypting a profile

python -m auto_apply --encrypt-profile

Prompts for a master password and writes a .vault file. The plaintext .json is deleted after a successful encryption. There is no recovery path if you forget the password — that is a property of the encryption, not an oversight.

Environment variables

Variable	Effect
AA_DATA_DIR	Root for all data AA writes. --portable sets it to ./data
AA_RANDOM_SEED	Equivalent to --seed
PYTHONIOENCODING	CI sets utf-8. AA reconfigures the console itself, so this is belt and braces

Exit behaviour

AA is a long-running interactive agent rather than a batch tool, and does not yet publish a stable exit-code contract. --check-config, --export-research, --research-summary, --research, --replay, --label, --encrypt-profile, --print-plan and the --search* builder flags exit after their work (a builder refusal prints a plain-language note and exits non-zero); the others run until you stop the session.

[PLANNED] — a documented exit-code table. Do not script against exit codes until it exists.