The command line
One command, vigile, runs the service, sets it up, and is a client of it. Every operation of the plan is a command of the same name.
How a command is read
vigile goes by its first words. serve starts the service. config, doctor, backup and restore-backup work on the files of an instance. user and every operation call the running service over HTTP.
vigile list-tasks --project WEB --status open
vigile set-task-status --id WEB-005 --version 1 --status in_progress --as agent1
vigile get WEB-005 --json
vigile help set-task-status
The commands here are typed in a terminal that is set up as Install and first run leaves it, with the instance running. The plan in them is the made-up one the pictures show.
Every command takes these two options:
| Option | What it is |
|---|---|
--config <file> | The instance to act on; or set VIGILE_CONFIG. |
--json | Print the raw result, and a failure as JSON on the error output, for scripts and agents. |
- There is no default instance. A command without
--configand withoutVIGILE_CONFIGstops and says so. vigile helplists the commands.vigile help <command>andvigile <command> --helpshow what one command takes:vigile help user,vigile help config set,vigile help create-task. A name that is no command is an error that lists what there is.vigile --versionprints the version.- An option may be written
--name valueor--name=value. A yes/no option stands alone, or says which:--draft,--draft false. Two hyphens alone end the options: what follows is taken as words.
Run
vigile serve
vigile serve [--name <text>] [--data_dir <text>] [--log_level <text>] [--listen.address <text>] [--listen.port <number>] [--auth.keyless_user <text>] [--backup.enabled <true|false>] [--backup.every_hours <number>] [--backup.folder <text>] [--backup.keep <number>]
Start the service: MCP, HTTP API and web page on one port. Runs until it is stopped. A setting given here counts for this run and is not written to the config.
| Option | What it is |
|---|---|
--name <text> | For this run: a label for this instance, shown in the web page and at startup. |
--data_dir <text> | For this run: where the data lives; relative paths start at the config file's folder. |
--log_level <text> | For this run: debug, info or quiet. |
--listen.address <text> | For this run: the address to listen on. |
--listen.port <number> | For this run: the port to listen on. |
--auth.keyless_user <text> | For this run: who a connection without an API key acts as; empty refuses such connections. |
--backup.enabled <true|false> | For this run: whether the service takes backups of the data by itself: true or false. |
--backup.every_hours <number> | For this run: how many hours lie between two automatic backups; 0.5 is half an hour. |
--backup.folder <text> | For this run: where automatic backups go; relative paths start at the config file's folder. |
--backup.keep <number> | For this run: how many automatic backups of each tenant are kept; older ones are removed. |
Each setting can be given for one run, as in --listen.port 8701. What a run is started with holds for the whole run. serve prints the addresses of the service and then a line for each change and each call that fails: see the log. With --json, a failure to start is reported as JSON; what it prints while it runs is the service's log.
It runs in the foreground. Ctrl-C, or a SIGTERM, finishes the write in flight and stops. A second serve on the same data folder refuses to start.
vigile doctor
vigile doctor
Check the config and the running service; changes nothing. Ends with an error when a check fails.
See Troubleshooting for what it checks.
vigile backup
vigile backup <folder>
Write a consistent copy of the data, while the service runs. The folder is created if needed. Each tenant becomes one file in it. The service also takes backups by itself: see the settings backup.enabled, backup.every_hours, backup.folder and backup.keep.
The config file, which holds the API keys, is not included. A backup cannot be written into the data folder itself. See Backups.
vigile restore-backup
vigile restore-backup <backup file> [--tenant <name>]
Put a backup in the place of the data, while the service is stopped. The file is one that vigile backup wrote, or one the service wrote by itself. Stop the service first.
| Option | What it is |
|---|---|
--tenant <name> | The tenant the file is a backup of, when the file's name does not say. |
What was there is set aside, not deleted. See Restoring a backup.
Set up
vigile config init
vigile config init [--name <name>] [--listen.address <address>] [--listen.port <port>]
Write a starter config with a new admin key. Refuses to replace a config file that is there.
| Option | What it is |
|---|---|
--name <name> | A label for the instance. |
--listen.address <address> | The address to listen on. Also taken as --address. |
--listen.port <port> | The port to listen on. Also taken as --port. |
vigile config show
vigile config show
Print the values in effect and where each came from.
Keys are masked.
vigile config set
vigile config set <setting> <value>
Change one setting, after checking it. Settings: name, data_dir, log_level, listen.address, listen.port, auth.keyless_user, backup.enabled, backup.every_hours, backup.folder, backup.keep.
The value is checked before it is written, and a value that fails the check is never written. See Configuration for each setting and for when a change applies.
For auth.keyless_user the running service is asked whether there is such a user. When no service runs on the config's data, the setting is written unchecked, with a warning. When the service cannot be asked for any other reason, because it does not answer, because something else answers at its address, or because the config names another machine's address, nothing is written.
vigile config unset
vigile config unset <setting>
Remove a setting so its default applies. Settings: name, data_dir, log_level, listen.address, listen.port, auth.keyless_user, backup.enabled, backup.every_hours, backup.folder, backup.keep.
vigile config path
vigile config path
Print where the config file is.
vigile user add
vigile user add <username> [--type <agent|person>]
Create a user; prints its API key and MCP settings.
| Option | What it is |
|---|---|
--type <agent|person> | What the user is; an agent when left out. |
It prints the new key, once, and the settings to paste into that agent's MCP configuration. The key applies at once, without a restart.
vigile user remove
vigile user remove <username> [--permanent]
Delete a user; its key stops working.
| Option | What it is |
|---|---|
--permanent | Remove the user for good: it cannot be brought back. |
vigile user reset-key
vigile user reset-key <username>
Issue a new key and cancel the old one.
For admin it also works when no service runs on the config's data, or when the service refuses the admin key: the new key is then written straight to the config file. When the service is there and does not answer, no key is written: the reset may still be carried out.
vigile user list
vigile user list
Show the users and how each connects.
vigile describe
vigile describe
Print what this version offers, as JSON. Operations with their inputs, commands, settings, errors, statuses, limits, the guide and what an agent is told over MCP. Needs no config and reads no plan: it describes the program, for documentation and for tools made from it.
The reference pages of this documentation are made from what it prints.
vigile help
vigile help [command]
List the commands, or show what one command takes. So does <command> --help. Vigile --version, with no command, prints the version.
A command for every operation
Each of the 21 operations is a command: its name with hyphens for underscores, and an option for each field of its input.
vigile create-task --project WEB --title "Cart page lists the items and the total" \
--description "Done when the total is right." --depends-on WEB-001,WEB-004
- Commands act as
adminunless given--as <username>. - The first word that is not an option is the item the command is about:
vigile get WEB-002isvigile get --id WEB-002. - A field that takes a list is given with commas:
--depends-on WEB-001,WEB-004. - A field that can be cleared takes
null:--why null. - An option of an operation may be written with hyphens or underscores:
--depends-onand--depends_onare the same. - A value with spaces needs quotes.
| Command | Options |
|---|---|
vigile create-project | --title <text> required--description <text>--prefix <text> |
vigile set-project-status | --id <text> required--version <number> required--status <open|in_preview|ready|broken|cancelled> required |
vigile list-projects | --has-problems--continuation <text> |
vigile list-history | --project <text>--parent <text>--text <text>--kind <project|task|user>--actor <text>--action <text>--status-from <draft|open|in_progress|paused|in_review|done|cancelled|in_preview|ready|broken>--status-to <draft|open|in_progress|paused|in_review|done|cancelled|in_preview|ready|broken>--from <text>--to <text>--continuation <text> |
vigile create-task | --title <text> required--description <text> required--why <text>--type <task|bug|issue|incident>--project <text>--parent <text>--priority <number>--value <number>--size <number>--depends-on <a,b,c>--assigned-to <a,b,c>--draft |
vigile update-task | --id <text> required--version <number> required--title <text>--type <task|bug|issue|incident>--description <text>--why <text>--priority <number>--value <number>--size <number> |
vigile set-task-status | --id <text> required--version <number> required--status <draft|open|in_progress|paused|in_review|done|cancelled> required |
vigile list-tasks | --project <text>--parent <text>--top-level--status <draft|open|in_progress|paused|in_review|done|cancelled>--type <task|bug|issue|incident>--assigned-to <text>--has-problems--continuation <text> |
vigile list-next-tasks | --project <text>--parent <text>--continuation <text> |
vigile list-stale-tasks | --project <text>--parent <text>--continuation <text> |
vigile get | --kind <project|task|user>--id <text> required--history--continuation <text> |
vigile delete | --kind <project|task|user>--id <text> required--version <number> required--permanent |
vigile restore | --kind <project|task|user>--id <text> required |
vigile override-timestamp | --kind <project|task>--id <text> required--version <number> required--name <created_at|completed_at> required--value <text> required |
vigile add-link | --from <text> required--type <text> required--to <text> required |
vigile remove-link | --from <text> required--type <text> required--to <text> required |
vigile list-link-types | none |
vigile create-user | --username <text> required--type <person|agent> required |
vigile list-users | --continuation <text> |
vigile reset-user-key | --user <text> required |
vigile get-guide | --topic <overview|organising|working|examples> |
Output, for people and for scripts
Without --json, a command prints its result in words and columns, in colour when the output is a terminal and plain when it is piped. A refusal is printed with the items in the way and the actions, where it has them:
✗ Task WEB-003 cannot be started: it is waiting for a dependency to finish.
· WEB-002 Cart page lists the items and the total open
→ Finish or cancel the items it depends on.
→ Or call remove_link with type "depends on" if the dependency no longer applies.
→ Or call list_next_tasks to pick work that can start now.
With --json, a command prints nothing but JSON: its result on the standard output, as the service gave it, or its failure on the error output, as {"error": {"code", "message"}}, with actions when there is something to do. That holds for every failure, also those of the command line itself; see the codes of the command line.
Before a command says anything in words about an answer, it checks that the answer is the one its operation gives to that call. Any other answer to a change is reported as an outcome that is not known; any other answer to a question as no answer to it. With --json the answer is passed on as it came, for the script to judge.
Exit codes
| Code | Means |
|---|---|
0 | The command did what it was asked. |
1 | The command reports a failure. Read the error before trying again: it says what happened, and what to do. |
2 | The service took the connection and its answer did not come, within 15 seconds or because the connection ended first. The code in the error is no_answer. |
An exit code of 1 does not by itself say that nothing was changed. Mostly nothing was, and in a few cases something was; the error tells them apart:
| The error | What was changed |
|---|---|
invalid_input, not_found, forbidden, version_conflict, rule_violation, limit_exceeded | Nothing. The call was refused before anything was stored. |
unauthorized | Nothing. The call was turned away before it reached an operation. |
internal, with a message that says what stands, as in "User keyless was created, but its API key could not be stored, so it cannot connect yet." | Part of it: what the message says stands, and it says what to do about the rest. |
internal, "The service hit an unexpected error. The change was not confirmed." | Not known. The same answer is given when the change was stored and when it was not. Look at the item, with get and its history, before sending the change again. |
And the errors of the command line itself:
| The error | What was changed |
|---|---|
usage, not_running, not_this_service, config_invalid, config_busy | Nothing. Nothing was sent to a service, and nothing was written |
cannot_start | It depends on how far the start had come: the steps of a start say what has happened by each |
| "Whether it was done is not known": the answer was not the one the operation gives | Not known. Look at the item with vigile get <id> --history before sending the change again |
| A change to the config that ends with an error saying that the change is in place | The change. It was written, and the system could not confirm that it will survive a power cut |
So a script that gets 1 reads the code and the message, with --json as {"error": {"code", "message"}}, and goes by them. It does not send a change again only because the exit code was 1.
After 2, a change that was sent may have been stored, or may be stored yet: the service carries out a request it has taken even after the connection has ended. The message says so, and how to look: vigile get <id> --history shows an item with the changes recorded in its history. See When a command gets no answer.
The command line and its service
A command takes its key from the config file, and first makes sure that what answers on the config's port is the service of this config: a running service holds the config's data folder, and what answers says it is a Vigile service of the config's name. If something else has the port, the command stops, says so, and has sent it nothing.
After a change of name, data_dir or [listen] in the config, the commands that call the service do not, until the service is started again: it is still what it was started as, and no longer what the config describes.
The command line never opens the data files to change them. Only doctor and backup open them, to read, and restore-backup replaces them while no service runs.