CLI reference

The package installs a researcher-profiles console script. Run researcher-profiles <subcommand> --help for per-command usage.

researcher-profiles <subcommand> [options]

Subcommand	Purpose	Extra required
`index`	Build or update a profile’s embedding index	`[embeddings]`
`search`	Query a profile’s embedding index	`[embeddings]`
`reset`	Archive a profile directory for a clean rebuild	core
`audit`	Audit a profile against all quality contracts	build package
`verify`	Verify one named contract (not yet implemented)	build package
`questions`	Inspect and decide human-review questions	core
`schema`	Export JSON Schema files for the profile format	core
`push`	Upload a built profile directory to a remote API server	`[client]`

The HTTP server has a separate entry point, python -m researcher_profiles.api; see the API reference.

index

Build (or incrementally update) the embedding index for a profile. The index is written to <profile>/meta/embeddings.sqlite.

researcher-profiles index <profile> [--force] [--backend SPEC]

Argument / flag	Description
`profile`	Path to a profile directory.
`--force`	Drop and rebuild the index from scratch.
`--backend SPEC`	Backend spec, e.g. `st:all-MiniLM-L6-v2`. Defaults to the profile’s recorded backend or the package default.

Prints a one-line report:

backend=st:all-MiniLM-L6-v2 added=4 updated=0 skipped=0 removed=0 duration=5.17s

Requires the [embeddings] extra.

search

Query a profile’s embedding index and print ranked hits.

researcher-profiles search <profile> <query> [-k N] [--type SOURCE_TYPE]

Argument / flag	Default	Description
`profile`	—	Path to a profile directory.
`query`	—	Free-text query.
`-k N`	`5`	Number of hits to return.
`--type SOURCE_TYPE`	none	Filter by source type: `paper_summary`, `expertise`, or `soul`.

Each hit prints its score, source, chunk index, section, and a text preview:

[0.595] expertise:expertise#1  Region set analysis
   ## Region set analysis Jane developed methods for enrichment analysis ...

Requires the [embeddings] extra.

reset

Archive a profile directory to a clean state for a rebuild, moving generated files into <profile>/.archive/<date>/ while preserving a default set (config.json, sources/manual/, and .archive/ itself).

researcher-profiles reset <profile> [--keep PATH ...] [--dry-run] [--force]

Flag	Description
`--keep PATH`	Relative path under the profile dir to preserve in addition to the defaults. May be passed multiple times.
`--dry-run`	Print what would be moved without changing anything.
`--force`	Overwrite an existing `.archive/<date>/` subdirectory.

reset requires a valid config.json in the profile directory; without one it exits with status 2.

audit

Audit a profile against the full set of quality contracts and print a report.

researcher-profiles audit <profile> [--json] [--quiet]

Flag	Description
`--json`	Emit the report as JSON instead of formatted text.
`--quiet`	Suppress OK lines; show only warnings and errors.

Exits 1 when the report contains any errors, 0 otherwise.

verify

Reserved subcommand for verifying a single named contract against a profile.

researcher-profiles verify <profile> <contract>

Currently a stub: it prints verify: not yet implemented and exits with status 2.

questions

Inspect and manually decide the human-review questions raised for a profile, stored in meta/questions.yaml.

researcher-profiles questions list <profile> [--pending | --all]
researcher-profiles questions show <profile> <question_id>
researcher-profiles questions decide <profile> <question_id> --decision {include|exclude} --decided-by NAME

Command	Description
`list`	List questions. `--pending` (default) shows only those awaiting a decision; `--all` shows every question. Output is YAML. A profile with no questions file prints `[]`.
`show <question_id>`	Show a single question by its ID. Exits `2` if not found.
`decide <question_id>`	Record a human decision. `--decision` is `include` or `exclude`; `--decided-by` identifies the decider. Both are required. Exits `2` if the ID is unknown.

schema

Export JSON Schema files for the on-disk profile format.

researcher-profiles schema export <out_dir>

Argument	Description
`out_dir`	Directory to write `<model>.schema.json` files into. Created if absent.

Writes five files and prints each path:

wrote schemas/profile_metadata.schema.json
wrote schemas/profile_config.schema.json
wrote schemas/papers_file.schema.json
wrote schemas/summary_file.schema.json
wrote schemas/question.schema.json

See Export JSON Schemas and the schema reference.

push

Upload a built profile directory to a remote API server (PUT /api/v1/profiles/{slug}). The directory’s contents are tarred (dotfiles like .archive/ excluded) and swapped into place atomically on the server; the profile is immediately listable, and matchable when it includes a built meta/embeddings.sqlite.

researcher-profiles push <profile-dir> --url <base-url> [--slug SLUG] [--token TOKEN]

Option	Description
`profile`	Path to a built profile directory (must contain `profile.yaml`).
`--url`	Server base URL, e.g. `http://localhost:8109` or a mounted prefix like `http://localhost:8130/rprofiles`. Required.
`--slug`	Target slug on the server. Default: the directory name.
`--token`	Bearer token. Default: the `RESEARCHER_PROFILES_TOKEN` env var.

$ researcher-profiles push profiles/jane-doe --url http://localhost:8109
pushed jane-doe (Jane A. Doe, level=lite, indexed=True)

Exit code 2 (with a message on stderr) on any failure: missing profile.yaml, auth rejection, or a server-side validation error. See the API reference for validation rules.