The trove command line
Every verb, option, output form and exit code of the trove tool
trove calls any OPAL task through the Trove door
of your user on this computer. It finds the door itself, from the door's
door.json, and it starts the Hub without its window when no Hub runs and the
Hub allows that.
trove [--text | --raw] [--label <text>] [--timeout <seconds>] [--door-folder <folder>] <verb> ...
Verbs
| Verb | What it does |
|---|---|
trove call <task> [<key>=<value> ...] |
Calls one task. Each argument is a <key>=<value> pair, and a value can hold spaces when your shell quotes it |
trove call '<json>' |
The envelope as JSON, {"task": ..., "args": {...}}, or a plan, {"steps": [...]}, whose steps run in order |
trove call @<file> |
The same JSON, read from a file |
trove serve |
Starts the standalone door host if no door runs, and prints the door |
trove door |
Prints the door: its endpoint, host, identity, protocol and process. Never its token |
trove spec <verb> ... |
Short for trove call spec.<verb> ... |
trove worktree <verb> ... |
Short for trove call worktree.<verb> ... |
trove session <verb> ... |
Short for trove call session.<verb> ... |
trove build <verb> ... |
Short for trove call build.<verb> ... |
trove door <verb> ... |
Short for trove call door.<verb> ... |
trove session follow <id> |
Prints the events of a session as they come, one JSON object per line, until you stop it |
The tool holds no list of tasks. It sends the name, and the door answers that
it knows no such task. A new task needs no new version of the tool. A spec.*
task on a door with no open spec database fails, and the message names the
identity that the door serves.
Options
An option can go before or after the verb: trove --text worktree list and
trove worktree list --text do the same.
| Option | Meaning |
|---|---|
--text |
The message of the task, then one line per output, key: value |
--raw |
The whole answer of the door, with ok and error |
--label <text> |
Names you in the plan's history and in the lease records. It is never a permission. The default is trove |
--timeout <seconds> |
How long to wait for an answer. The default is 600 seconds |
--door-folder <folder> |
Use the door in this folder instead of your user's. Tests use it |
Output
The outputs of the task go to standard output, as JSON by default. If the task
gave a message, it is in the output message. The reads of the spec database
give their data as the message: spec.get, spec.tree and spec.search put a
JSON document there, and the tool prints it as JSON. An output that holds a
JSON list or object, as projects of trove.projects, prints as JSON too. Every error goes to
standard error, one line each. A plan of steps prints the outputs of its last
step.
Measure a probe
A session of a recurring spec measures
its own work while it works, with the task measure.run. The briefing of the
run names the key of each probe.
trove call measure.run probe=m0123456789 folder="$PWD"
trove call measure.run probe=m0123456789 lane=2
trove --text call measure.run probe=m0123456789 folder="$PWD"
Name the folder to measure: folder= takes an absolute path to a checkout,
and lane= takes the worktree of a lane. The output value is the number. The
message is a JSON object with the probe, its name, the value, the folder and
the first 50 findings, each with path, line and text.
measure.run records nothing. Trove records the before and after values of a
run itself, so the number that a session prints never becomes a sample. The
task needs no scope, and never asks.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The task completed |
| 1 | The task ran and failed, the door knows no such task, or no answer came. The message is the task's error |
| 2 | The command line is wrong. The message shows the usage of the verb |
| 3 | No door runs, and the Hub does not allow a door without its window. The message names the setting |
| 4 | The door refused the call: the token, a scope you did not grant, or a task that asks before every call where nobody can answer. For a scope, the message names it and the page that grants it: Apps, Trove, the Settings tab, Door permissions |
| 5 | The door speaks another protocol. The message names both versions |
| 6 | The door stayed busy after three tries. The message names the resource |