The prem command
Every prem command with its arguments and options, as the program prints them. prem with no arguments prints the usage these sections are taken from; prem setup --help and prem remove --help print their own; every other command prints its usage lines when it is called with no subcommand or with one it does not know, which needs a configured database first, because every command but setup and remove connects before it reads its arguments. There is no --help switch on the other commands.
The database a command uses, and the embedding provider, come from the environment; the variables are listed at the end of this page and on Configuration.
01Who may read, in the program's words
Who may read a document is decided by folder rules (prem rules), and a folder no rule covers is readable by nobody. Search defaults to what everyone may read. There is no flag that quietly widens either one.
02prem migrate
Applies the numbered migrations the build carries, or verifies that the schema is current. Every other command does the same before it runs.
prem migrate (alias: init-db)
03prem setup
Installs the database side of PremAgentic on a PostgreSQL that already exists. The usage lists it as:
prem setup [--plan] ... (install on an existing PostgreSQL; prem setup --help)
prem setup --help prints this:
prem setup [--plan] [--database name] [--owner-role name] [--app-role name] [--search-role name]
[--credentials-dir dir] [--admin-connection-file file]
[--admin-user name] [--admin-password-file file]
[--host-name name] [--https-port port]
[--windows-service] [--api-path file]
[--bundled-postgres folder --data-dir folder [--postgres-port port]]
Installs Premagentic on a PostgreSQL that already exists (14 or later), then
searches as the application role to prove it works. Safe to run again: a
finished install is left as it is, and a half-finished one is completed.
--plan report every step and change nothing
--database name the database to create or use (default: premagentic)
--owner-role name owns the schema; runs migrations and rebuild-index (default: premagentic_owner)
--app-role name reads and writes rows, nothing else (default: premagentic_app)
--search-role name reads documents and chunks for a caller, nothing else (default: premagentic_search)
--credentials-dir dir where the credentials files, the HTTPS certificate and its settings are
written (default: the Premagentic folder in this account's local application
data, or C:\ProgramData\Premagentic with --windows-service)
--admin-connection-file a file holding a line connection=<connection string> for a role that
can create roles and databases
--admin-user name make this sign-in name the first administrator, when no administrator
exists yet. Its password is asked for, or read from --admin-password-file
--admin-password-file a file whose first line is the first administrator's password
--host-name name the name clients use for the API; the self-signed HTTPS certificate is
made for it (default: this computer's name)
--https-port port the API's HTTPS port (default: 8443)
--windows-service register the API as the Windows service Premagentic, under its own
virtual account (needs an elevated prompt; the service is not started)
--api-path file the API program the service runs (default: Premagentic.Api.exe beside prem)
--bundled-postgres dir the pgsql folder of the PostgreSQL bundled with Premagentic on Windows. Setup
makes a cluster in --data-dir, listening on localhost only, starts it (as a
service with --windows-service), and uses its superuser instead of an admin
connection. The superuser's password goes to postgres.credentials, readable by
this account and administrators only. Needs the Visual C++ 2015 to 2022 x64 runtime
--data-dir dir where the bundled server keeps its data (default: the Premagentic folder in
C:\ProgramData with --windows-service, else in this account's application data)
--postgres-port port the bundled server's port on localhost (default: 5432)
The admin connection comes from --admin-connection-file or from
PREM_SETUP_ADMIN_CONNECTION. Generated passwords are written only to the
credentials files and the HTTPS settings, and are never printed. Point the
application at its file with PREM_CREDENTIALS_FILE; point it at
owner.credentials only to migrate or rebuild the index. Every connection
setup writes uses GSS Encryption Mode=Disable unless the admin connection
sets that key itself.
04prem remove
Takes away what prem setup registered and keeps the data unless told otherwise. The usage lists it as:
prem remove [--plan] [--purge --yes] (take away the services; the data stays without --purge)
prem remove --help prints this:
prem remove [--plan] [--purge [--yes]] [--credentials-dir dir] [--windows-service]
[--admin-connection-file file] [--bundled-postgres folder] [--data-dir folder]
Takes away what prem setup registered, and keeps the data. The Windows
services Premagentic and PremagenticDb are stopped and removed where they
exist (from an elevated prompt); on Linux the systemd steps are printed for
root to run. The database, its three roles, the credentials files and a
bundled server's data folder all stay, so prem setup run again uses them.
--plan report every step and change nothing
--purge delete the data as well: drop the database as its owner, from owner.credentials,
and the three roles as the admin role, stop the bundled server and delete its data
folder, then delete the credentials files. Every document, user, setting and the
audit trail goes, and it cannot be undone
--yes carry out --purge; without it the purge is listed and nothing is changed
--credentials-dir dir where setup wrote the credentials files (default: as for prem setup)
--windows-service the install was made with --windows-service, so the defaults are in C:\ProgramData
--admin-connection-file a file holding a line connection=<connection string> for a role that can drop
roles, for --purge on a PostgreSQL that existed before Premagentic. The owner
cannot: setup makes it without that right. A bundled server's superuser is read
from postgres.credentials instead
--bundled-postgres dir the pgsql folder of the bundled PostgreSQL, to stop a server started by hand
--data-dir dir the bundled server's data folder (default: as for prem setup, when the install
has a bundled server)
The admin connection comes from --admin-connection-file or from
PREM_SETUP_ADMIN_CONNECTION, as for setup, and is never printed.
05prem rebuild-index
Empties the index so the next ingest rebuilds it.
prem rebuild-index --confirm
The options, as the program explains them:
--confirm rebuild-index only: empty every index table so the next ingest rebuilds it.
Users, settings and the audit trail are not touched.
06prem ingest
Reads a folder, or a registered source, into the index.
prem ingest <folder> [--public | --principals a,b] [--prefix p] [--okf-bundle] [--undeclared-as-machine] [--allow-empty-source] prem ingest --source <name> [--allow-empty-source]
The options, as the program explains them:
--public ingest: set the folder's rule to allow everyone, then ingest
--principals a,b ingest: set the folder's rule to allow these, then ingest.
Principals are written by name: group:Staff, user:alice, everyone
--okf-bundle ingest: read the folder as an Open Knowledge Format bundle
--undeclared-as-machine ingest: in a bundle, treat a concept that does not say who wrote it as
machine-written and unverified, so agents do not see it until a person signs it off
--source name ingest: read a registered source (prem sources), with its folder, prefix and settings
--allow-empty-source permit deletion of every indexed document under the prefix when the
source yields nothing. Off by default, because an unmounted volume or a
revoked permission looks exactly like an emptied folder.
Called with no folder, or with a flag where the folder should be, it prints a usage line that also names --chunker name, which the usage above leaves out:
Usage: prem ingest <folder> [--public | --principals a,b] [--prefix p] [--okf-bundle] [--undeclared-as-machine] [--chunker name]
prem ingest --source <name> [--allow-empty-source]
07prem search
Runs a query as a caller and prints the cited passages.
prem search "<query>" [--user name | --with-token | --as a,b | --unrestricted <reason>] [--historical] [--top N]
The options, as the program explains them:
--user name run the query as this Premagentic user, with the user's groups as they are now --with-token run the query as the agent whose token is read from standard input --as a,b run the query as a caller holding these principals, by name --unrestricted r bypass the document gate; recorded on the event with reason r
08prem section
Fetches one document, or one heading of it, as a caller.
prem section <path> [heading] [--user name | --with-token | --as a,b | --unrestricted <reason>] [--historical]
The options, as the program explains them:
--user name run the query as this Premagentic user, with the user's groups as they are now --with-token run the query as the agent whose token is read from standard input --as a,b run the query as a caller holding these principals, by name --unrestricted r bypass the document gate; recorded on the event with reason r
09prem eval
Runs a golden question set against the index and writes a report.
prem eval <golden-questions.json> [reportPath]
10prem users
Accounts that sign in.
prem users add <sign-in-name> [--display "Name"] [--role administrator|auditor|member] [--password] prem users disable|enable <sign-in-name> prem users set-password <sign-in-name> prem users list
The options, as the program explains them:
--password users add: read a password from standard input or a prompt
11prem groups
Groups, their members, and what an outside directory's groups mean here.
prem groups add <name> prem groups rename <name> <new-name> prem groups remove <name> [--force] prem groups members <name> [--add a,b] [--remove c,d] prem groups list prem groups map <external-principal> <group> prem groups unmap <external-principal> prem groups mappings
12prem agents
Agents, who they act for, where their model runs, and what they are granted.
prem agents add <name> --owner <sign-in-name> --mode acts-for-user|service --model local|hosted [--vendor "Name"] [--rate N] [--min-trust tier] prem agents set <name> --model local|hosted [--vendor "Name"] prem agents disable|enable <name> prem agents grant|ungrant <agent> <group> prem agents list
13prem tokens
The tokens agents present.
prem tokens issue <agent> [--days N] prem tokens revoke <token-id> prem tokens list [<agent>]
14prem rules
The folder rules that decide who may read a folder.
prem rules set [--source s] [--prefix p] (--public | --principals a,b | --entry "allow group:Staff" ...) prem rules remove [--source s] [--prefix p] prem rules list
15prem settings
The deployment's settings and the change record.
prem settings list
prem settings get <key>
prem settings set <key> <value> (a retrieval value is JSON: 40, 0.5, or {"default": 1.0})
prem settings unset <key> (a retrieval setting or the golden set path goes back to its default)
prem settings history [--limit N] (the change record, newest first)
16prem sources
Registered folders, their settings, their runs, and the chunkers they may name.
prem sources add <name> <folder> [--prefix p] [--okf-bundle] [--undeclared-as-machine] [--chunker name]
prem sources set <name> [--okf-bundle on|off] [--undeclared-as-machine on|off] [--chunker name]
[--owner <sign-in name>] [--hosted yes|no]
prem sources remove <name>
prem sources list
prem sources status <name>
prem sources chunkers (the chunkers a source may name)
17prem extensions
What this deployment loads from its extensions folder, and what it allows.
prem extensions list (what loaded, what did not and why, and what is allowed) prem extensions allow <folder> (allow that folder's extension, by the hash of the assembly there) prem extensions disallow <name> (stop allowing every hash under that name)
18prem audit
The audit trail's retention.
prem audit prune [--plan] (deletes what is past audit.retention_days; --plan only says what it would)
19prem profile
A folder of plain files carrying a whole configuration.
prem profile validate <folder> (check it against this deployment and change nothing)
prem profile apply <folder> (apply it, or refuse the whole profile)
prem profile show [<folder>] (what is applied, and how this deployment differs from a profile)
--golden-set-dir F (where a profile's golden set is copied; the server has to read it)
20Environment
The variables the usage lists, as printed:
PREM_CREDENTIALS_FILE the app.credentials file prem setup wrote; how an installed deployment connects
PREM_CONNECTION_STRING a PostgreSQL connection string instead; set one of these two, not both
PREM_DEV_DATABASE=1 the local development database in docker-compose.yml, when neither is set
With none of the three, every command but setup refuses to start.
PREM_EMBEDDING_PROVIDER local | openai | hash, or one an extension registered (default: local, fully offline)
PREM_ONNX_MODEL_DIR (default: ./models/minilm)
PREM_EXTENSIONS_DIR the folder whose subfolders hold extensions, when the setting
extensions.folder does not say. Neither one means no extensions.
PREM_TENANT_KEY (default: default)
PREM_HEADING_PREFIX 0 disables the "title > heading" embedding context prefix (default on)