Vigile
SearchContents

Documentation

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:

OptionWhat it is
--config <file>The instance to act on; or set VIGILE_CONFIG.
--jsonPrint the raw result, and a failure as JSON on the error output, for scripts and agents.
  • There is no default instance. A command without --config and without VIGILE_CONFIG stops and says so.
  • vigile help lists the commands. vigile help <command> and vigile <command> --help show 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 --version prints the version.
  • An option may be written --name value or --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.

OptionWhat 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.

OptionWhat 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.

OptionWhat 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.

OptionWhat 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.

OptionWhat it is
--permanentRemove 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 admin unless given --as <username>.
  • The first word that is not an option is the item the command is about: vigile get WEB-002 is vigile 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-on and --depends_on are the same.
  • A value with spaces needs quotes.
CommandOptions
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-typesnone
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

CodeMeans
0The command did what it was asked.
1The command reports a failure. Read the error before trying again: it says what happened, and what to do.
2The 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 errorWhat was changed
invalid_input, not_found, forbidden, version_conflict, rule_violation, limit_exceededNothing. The call was refused before anything was stored.
unauthorizedNothing. 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 errorWhat was changed
usage, not_running, not_this_service, config_invalid, config_busyNothing. Nothing was sent to a service, and nothing was written
cannot_startIt 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 givesNot 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 placeThe 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.