Run it with ./lens, so it acts on the installation you chose.

Run every administration command with ./lens, from the installation directory. The installation must be running.

A command typed straight into your own shell knows nothing about the installation. It cannot reach the installation’s database or meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log., which stay on Docker’s private network.

What ./lens does for each command

1. It finds the installation: the --directory option, then the NOVUSLENS_INSTALL_DIR variable, then the directory that holds lens.
2. It reads .novuslens.env and checks it as setup does. Your shell’s CONWAY_, NOVUSLENS_, MYCELIUM_, COMPOSE_, POSTGRES_ and DATABASE_ variables never reach the command.
3. It copies each host file the command reads into the service, as Give files from the host describes.
4. It runs the command in the running reasoning service, with the installation’s configuration, on its private network.
5. It copies each output file back to the host, then deletes the copies it made in the service.

The commands

Two commands carry the administration. ./lens graph runs python -m conway_graph, the read modelRead modelThe database tables used by the map, Ask and Find. NovusLens rebuilds these tables from its history of recorded changes. and accounts. ./lens connectors runs python -m conway_connectors, the evidence imports. Each command takes a verb, then that verb’s flags. --org is an ordinary flag after the verb.

./lens reads only --directory and --version as its own options. Put them after graph or connectors and before the verb, as in ./lens graph --directory /srv/lens create-viewer --help. Everything after the verb belongs to the command. ./lens graph --help and ./lens connectors --help list the verbs. Every verb takes --help and lists its own flags, as in ./lens connectors document --help. A missing required flag, or a bad --role, is refused on this host before Docker runs.

Every ./lens graph verb takes --rich (the default), --plain or --json to choose its output. --wizard asks for each flag in turn, as in ./lens create-viewer --wizard; on the host it lets the required flags be left out. It needs a terminal for both input and output, so lens refuses it when you pipe or redirect the command.

./lens keyperson, ./lens document, ./lens acquire, ./lens correct, ./lens agents, ./lens agent-source and ./lens notify are not commands, and graph and connectors take no --. Each of these forms exits with an error that names the command to use instead. ./lens exec -- … and ./lens compose -- … keep their --.

./lens backup, ./lens restore and ./lens forget-org are installer commands. They have their own pages: Backup and restore and Accounts and stewardship.

Give files from the host

./lens copies a host file given with --file, --mapping, --fixture or --enrolment into the service before the command runs. It copies a host path given with --out back to the host after the command succeeds. For example, this pair writes an enrolmentEnrolmentThe operator's recorded permission for a source to send specified record types about named agents, using an identified signing key. record on the host and then reads it back:

./lens connectors agent-source enrol --org <org> ... --out product-source.json
./lens connectors agent-source activate --org <org> --viewer <operator-login> --enrolment product-source.json

Keep these files outside /tmp. Inside the service, a /tmp path names the service’s own file.

Any other file option names a path inside the service. Send that file on standard input first:

./lens exec -- sh -c 'cat > /tmp/input.json' < input.json

Then give /tmp/input.json to that option.

Reach the services

./lens graph materialise and ./lens graph requeue contact the mesh and need --host mesh-0. The interview command ./lens exec -- python -m conway_mesh.build needs it too. ./lens graph keyperson reads the installation’s configured mesh address, mesh-0, so it needs no --host. The reasoning service has no host port. Commands reach it inside the installation’s network.

When something goes wrong