Command line

Script Agnos from a terminal: add and clean files, build exports, or watch a folder, without opening the window.

The command line comes with every copy of Agnos. It follows the same checks and licence rules as the window, and starts Agnos in the background if it is not running.

Run it

The command line is agnos_cli.py in the program folder, run with the Python in its runtime folder. In Command Prompt:

cd /d "%LOCALAPPDATA%\Programs\Agnos"
runtime\python.exe agnos_cli.py status

In PowerShell:

cd "$env:LOCALAPPDATA\Programs\Agnos"
.\runtime\python.exe agnos_cli.py status

From any other folder, for example in a scheduled job, give both paths in full:

"%LOCALAPPDATA%\Programs\Agnos\runtime\python.exe" "%LOCALAPPDATA%\Programs\Agnos\agnos_cli.py" status

Add --help to list the commands, or after a command to list its options. The examples below run from the program folder.

Commands

Where a command takes PROJECT, give the project's name (capitals do not matter) or its id. Use the id if two projects share a name; projects list shows it.

Command	What it does
`status`	Whether Agnos is running, its version, where the data lives, the licence, and the projects. It starts nothing.
`projects list [--archived]`	Every project with its id, purpose and file counts. `--archived` includes archived projects.
`projects create NAME [--purpose ID]`	Starts a project. `--purpose` is one of `rag`, `general_docs`, `default`, `llm_training`, `paragraph`, `deep_clean`, `code`, `no_chunking`, `large_files` or `fast`. Without it, the project starts from the default settings.
`add PROJECT PATH [PATH ...]`	Adds files, and every file in a folder and its subfolders. Files Agnos cannot read are listed with the reason.
`clean PROJECT [--stale] [--wait]`	Cleans files that are waiting. `--stale` also cleans files cleaned with older settings. `--wait` returns only when nothing is waiting or running.
`jobs PROJECT [--limit N]`	What is running, waiting, done and failed, and the latest jobs (20 unless you give `--limit`).
`review PROJECT [--file ID]`	The project's totals and what was removed, by rule. `--file` reports one file.
`export PROJECT --out DIR [options]`	Builds an export into `DIR`. See Exporting.
`watch PROJECT FOLDER --out DIR [options]`	Watches a folder and keeps a fresh dataset in `DIR`. See The watched folder.
`stop`	Stops an Agnos the command line started. An Agnos you opened yourself is left running.

Two options work with every command:

--json: Prints one JSON object instead of a report: "ok": true and the result, or "ok": false with error, and hint and code when there are any.
--no-start: Fails instead of starting Agnos when it is not running.

Example

From a new project to a dataset:

runtime\python.exe agnos_cli.py projects create "support handbook" --purpose rag
runtime\python.exe agnos_cli.py add "support handbook" C:\Users\me\Documents\handbook
runtime\python.exe agnos_cli.py clean "support handbook" --wait
runtime\python.exe agnos_cli.py review "support handbook"
runtime\python.exe agnos_cli.py export "support handbook" --profile rag --out C:\datasets

Files are cleaned as they are added unless the project's automatic cleaning is off, so clean --wait here mostly waits for that to finish.

Exporting

--out DIR: Required. The folder to save the export in; it is created if needed.
--profile: rag (RAG corpus, the default), documents (Cleaned documents), training (Training data) or bundle (Everything). See Export formats.
--split: The share of files held back for validation, such as 0.1. Training data and Everything only.
--seed: The seed for the split; 42 unless you give one.
--name: The dataset's file name; agnos-dataset unless you give one.

An export never overwrites a file: if the name is taken, Agnos adds -2, -3 and so on. It uses each kind's default options, and applies your choices in Review.

The watched folder

watch turns a folder into an inbox. Documents that land in it are added, cleaned and exported to another folder, until you press Ctrl + C.

runtime\python.exe agnos_cli.py watch "support handbook" C:\inbox --out C:\datasets --interval 30

--out DIR: Required. The folder datasets are saved in.
--interval: Seconds between looks at the folder; 30 unless you give one.
--profile, --split, --seed: As for export.

A file is taken once it stops changing between two looks, so a file still being copied waits.
Each file is sent once, and again only if it is saved again. Subfolders are watched too.
A file Agnos cannot read is reported once, then left alone.
After new work, once nothing is still cleaning, Agnos saves a new export under a new name. Earlier ones are kept.
A file deleted from the folder stays in the project.
Agnos never writes to the watched folder.

If an export is refused, for example after the trial, the watcher says so once and keeps adding and cleaning. It tries again when a new document arrives.

Exit codes

Code	Meaning
`0`	Done. This includes `status` when Agnos is not running, `stop` with nothing to stop, and `watch` stopped with `Ctrl` + `C`.
`1`	The command failed, including a refused file or export. The error output says why in one sentence.
`2`	No command was given, or it could not be read. The usage is printed.
`130`	Stopped with `Ctrl` + `C` before it finished.

With --json, a failed command exits with the same code and also prints its "ok": false object.

Licence

During the 14-day trial every export works. After it, status, projects, add, clean, jobs and review keep working, and export exits with code 1:

Your 14-day trial has ended. Exporting needs a Pro licence ($99, once). Your projects, cleaning and Review keep working.

The command line has no licence command. Enter your key in the window, on the Licence page, and the command line can export straight away. See Trial and licences.