Command reference
Every asbuilt command with its options, defaults and environment variables.
asbuilt is the one program behind ruumica’s checks and exports. Every command and option is listed here exactly as asbuilt <command> --help prints it; this page is generated from the program, so it cannot fall behind it.
An option marked [env: NAME=] can also be set through the environment variable NAME.
asbuilt
asbuilt kernel CLI (db | crs | sor | laz | package | export | sync)
Usage: asbuilt <COMMAND>
Commands:
db Database migrations
crs Geodetic pipelines: verify vectors/grids, transform points, sync registry to the DB
sor OTDR .sor files
laz LAS/LAZ point clouds
package The frozen AsBuiltPackage: build it from PostGIS, derive the BoQ
export Closeout package: every exporter + package.json + raw evidence in a deterministic ZIP
sync Offline sync (M3): inspect the server's op state
worker The sync worker (M3): pull job messages from the queue and apply them to PostGIS
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
asbuilt db
Database migrations
Usage: asbuilt db <COMMAND>
Commands:
migrate Apply pending migrations from db/migrations (embedded at build time)
status Show applied migrations
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
asbuilt db migrate
Apply pending migrations from db/migrations (embedded at build time)
Usage: asbuilt db migrate --database-url <DATABASE_URL>
Options:
--database-url <DATABASE_URL> [env: DATABASE_URL=]
-h, --help Print help
Run it after installing ruumica and after every upgrade. It applies the database changes that are not applied yet and changes nothing when all are. Writes to the database in DATABASE_URL.
asbuilt db status
Show applied migrations
Usage: asbuilt db status --database-url <DATABASE_URL>
Options:
--database-url <DATABASE_URL> [env: DATABASE_URL=]
-h, --help Print help
Lists the database changes that are applied. Reads only.
asbuilt crs
Geodetic pipelines: verify vectors/grids, transform points, sync registry to the DB
Usage: asbuilt crs <COMMAND>
Commands:
verify Run every test vector of the registered pipelines and check required grids
transform Transform one lon/lat/h through a pinned pipeline
sync-db Upsert crs_pipelines + crs_test_vectors from geodesy/pipelines/*.toml
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
asbuilt crs verify
Run every test vector of the registered pipelines and check required grids
Usage: asbuilt crs verify [OPTIONS]
Options:
--registry <REGISTRY>
Directory with pipeline TOML files [default: geodesy/pipelines]
--all
Verify every pipeline (default when --pipeline is absent)
--pipeline <PIPELINE>
Verify one pipeline id
--json
--require-official-vectors
Fail unless every pipeline has ≥ 5 official (non-definition) vectors and none FAIL
--missing-grid-must-fail
Prove that removing a required grid makes the pipeline fail (never 2D output)
--allow-grid-absent <ALLOW_GRID_ABSENT>
Glob of pipeline ids whose GRID_ABSENT status is tolerated (e.g. 'ee.*'); repeatable
-h, --help
Print help
Proves that the coordinate pipelines give the official coordinates on this machine. Every pipeline has official test points; each must PASS. Every grid file is checked against its recorded SHA-256. Reads only; exits 1 when anything fails. Statuses: OK, ABSENT, MISMATCH, HASH_PENDING for grids; PASS, FAIL, GRID_ABSENT, ERROR for test points.
Example, one Norwegian pipeline (the first line names the PROJ version of the machine):
$ asbuilt crs verify --pipeline no.euref89.utm32-nn2000.v1
…
no.euref89.utm32-nn2000.v1 official=6 pass=6 fail=0 grid_absent=0 OK
grid no_kv_HREF2018B_NN2000_EUREF89.tif ok
asbuilt crs transform
Transform one lon/lat/h through a pinned pipeline
Usage: asbuilt crs transform [OPTIONS] --pipeline <PIPELINE> <LON> <LAT> <H>
Arguments:
<LON>
<LAT>
<H>
Options:
--registry <REGISTRY> [default: geodesy/pipelines]
--pipeline <PIPELINE>
--precision <PRECISION> Decimals printed (default 3 = mm) [default: 3]
-h, --help Print help
Converts one position (longitude and latitude in degrees, ellipsoidal height in metres) through a pinned pipeline and prints easting, northing and height in metres, to the millimetre. A pipeline whose grid is missing refuses with an error; it never prints a position without its height.
$ asbuilt crs transform --pipeline no.euref89.utm32-nn2000.v1 10.75 59.91 100.0
597868.381 6642681.510 60.896
asbuilt crs sync-db
Upsert crs_pipelines + crs_test_vectors from geodesy/pipelines/*.toml
Usage: asbuilt crs sync-db [OPTIONS] --database-url <DATABASE_URL>
Options:
--registry <REGISTRY> [default: geodesy/pipelines]
--database-url <DATABASE_URL> [env: DATABASE_URL=]
-h, --help Print help
Copies the pipeline registry (geodesy/pipelines/*.toml) and its test points into the database, where projects refer to them. Run it after the registry changes. Running it again changes nothing.
asbuilt sor
OTDR .sor files
Usage: asbuilt sor <COMMAND>
Commands:
inspect Parse a .sor file and print its blocks (canonical JSON with --json)
ingest Evaluate a trace, pair it with the opposite direction if on record, locate its events along the cable route and store it (otdr_traces, otdr_event_locations)
pair Pair two opposite traces of one fibre and judge them bidirectionally (no database)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
asbuilt sor inspect
Parse a .sor file and print its blocks (canonical JSON with --json)
Usage: asbuilt sor inspect [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--json
--strict-checksum Exit 1 when the stored checksum matches no known algorithm (default: WARNING finding)
-h, --help Print help
Reads a .sor file and prints what it contains. Writes nothing. Codes: SOR_CHECKSUM_MISMATCH, SOR_NO_CKSUM_BLOCK, SOR_NO_DATAPTS, SOR_NO_KEYEVENTS, SOR_LANGUAGE_INVALID, SOR_TRAILING_BYTES.
asbuilt sor ingest
Evaluate a trace, pair it with the opposite direction if on record, locate its events along the cable route and store it (otdr_traces, otdr_event_locations)
Usage: asbuilt sor ingest [OPTIONS] --database-url <DATABASE_URL> --blob-dir <BLOB_DIR> --project <PROJECT> --cable <CABLE> --fiber <FIBER> --direction <DIRECTION> --from-node <FROM_NODE> --to-node <TO_NODE> <FILE>
Arguments:
<FILE>
Options:
--database-url <DATABASE_URL> [env: DATABASE_URL=]
--blob-dir <BLOB_DIR> [env: ASBUILT_BLOB_DIR=]
--project <PROJECT> Project UUID or unique name
--cable <CABLE> Cable UUID or label
--fiber <FIBER>
--direction <DIRECTION> A_TO_B = measured along the cable route, B_TO_A = against it
--from-node <FROM_NODE> Node (UUID or label) the OTDR was connected at
--to-node <TO_NODE>
--ior <IOR> Group index (IOR) to use instead of the file's, e.g. from the cable data sheet. 1.40–1.60, at most 5 decimals. Applies to this file only; re-ingesting without it returns the file to its own group index
--json
-h, --help Print help
Judges an OTDR trace against the project’s limits and stores it on its cable and fibre. When the opposite direction of the same fibre is already stored, the two are judged as a pair. The event positions are placed along the cable route. The file is kept in the blob folder under its SHA-256. Codes: the OTDR group of Codes and statuses.
asbuilt sor pair
Pair two opposite traces of one fibre and judge them bidirectionally (no database)
Usage: asbuilt sor pair [OPTIONS] <AB> <BA>
Arguments:
<AB> Trace measured from end A (A→B)
<BA> Trace of the same fibre measured from end B (B→A)
Options:
--ior-ab <IOR_AB>
Group index override for the A→B file (see `sor ingest --ior`)
--ior-ba <IOR_BA>
Group index override for the B→A file
--max-splice-db <MAX_SPLICE_DB>
Splice loss limit, dB (default = the projects table default) [default: 0.3]
--max-connector-db <MAX_CONNECTOR_DB>
Connector loss limit, dB [default: 0.75]
--max-reflectance-db <MAX_REFLECTANCE_DB>
Reflectance limit, dB (negative) [default: -35]
--json
Accepted for symmetry; the output is always canonical JSON
-h, --help
Print help
Judges two traces of one fibre, one from each end, as a pair, without a database. Use it to check a pair before ingesting it. Codes: BIDIR_WAVELENGTH_MISMATCH, BIDIR_LENGTH_MISMATCH, BIDIR_NO_END_EVENT, OPTICAL_EVENT_OVER_LIMIT, OPTICAL_TOTAL_LOSS_OVER_LIMIT.
asbuilt laz
LAS/LAZ point clouds
Usage: asbuilt laz <COMMAND>
Commands:
inspect Validate header vs. content of a LAS/LAZ file and hash it
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
asbuilt laz inspect
Validate header vs. content of a LAS/LAZ file and hash it
Usage: asbuilt laz inspect [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--json
-h, --help Print help
Checks that a LAS or LAZ point cloud is internally consistent and prints its SHA-256. Writes nothing. Codes: the Point clouds group.
asbuilt package
The frozen AsBuiltPackage: build it from PostGIS, derive the BoQ
Usage: asbuilt package <COMMAND>
Commands:
build Print the canonical package JSON (the `package.json` of a closeout ZIP)
boq Print the bill of quantities of the package (integer mm / pieces)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
asbuilt package build
Print the canonical package JSON (the `package.json` of a closeout ZIP)
Usage: asbuilt package build [OPTIONS]
Options:
--project <PROJECT> Project UUID or unique name
--frozen-at <FROZEN_AT> Freeze instant, exactly `YYYY-MM-DDTHH:MM:SSZ`
--blob-dir <BLOB_DIR> Content-addressed blob directory (`<dir>/raw/<sha256>`) [env: ASBUILT_BLOB_DIR=]
--database-url <DATABASE_URL> [env: DATABASE_URL=]
--from-package <FROM_PACKAGE> Use this package.json instead of the database (no DB access at all)
--json Accepted for symmetry with other commands; output is always canonical JSON
-h, --help Print help
Prints the frozen package of a project: everything an export contains, as of the freeze instant, in one canonical JSON document. It is the package.json inside every closeout ZIP. Writes nothing.
asbuilt package boq
Print the bill of quantities of the package (integer mm / pieces)
Usage: asbuilt package boq [OPTIONS]
Options:
--project <PROJECT> Project UUID or unique name
--frozen-at <FROZEN_AT> Freeze instant, exactly `YYYY-MM-DDTHH:MM:SSZ`
--blob-dir <BLOB_DIR> Content-addressed blob directory (`<dir>/raw/<sha256>`) [env: ASBUILT_BLOB_DIR=]
--database-url <DATABASE_URL> [env: DATABASE_URL=]
--from-package <FROM_PACKAGE> Use this package.json instead of the database (no DB access at all)
--json Accepted for symmetry with other commands; output is always canonical JSON
-h, --help Print help
Prints the bill of quantities of the frozen package. Example with the demo project. Quantities are whole millimetres (mm) or pieces (pcs):
$ asbuilt package boq --project ee-demo --frozen-at 2026-01-01T00:00:00Z
{
"lines": [
{
"category": "CABLE_ROUTE_LENGTH_3D",
"item": "FO-12-002",
"quantity": 129619,
"unit": "mm"
},
…
asbuilt export
Closeout package: every exporter + package.json + raw evidence in a deterministic ZIP
Usage: asbuilt export [OPTIONS] --profile <PROFILE> --out <OUT>
Options:
--project <PROJECT>
Project UUID or unique name
--frozen-at <FROZEN_AT>
Freeze instant, exactly `YYYY-MM-DDTHH:MM:SSZ`
--blob-dir <BLOB_DIR>
Content-addressed blob directory (`<dir>/raw/<sha256>`) [env: ASBUILT_BLOB_DIR=]
--database-url <DATABASE_URL>
[env: DATABASE_URL=]
--from-package <FROM_PACKAGE>
Use this package.json instead of the database (no DB access at all)
--json
Accepted for symmetry with other commands; output is always canonical JSON
--profile <PROFILE>
Export profile id (`<profile-dir>/<id>.toml`)
--profile-dir <PROFILE_DIR>
[default: profiles]
--registry <REGISTRY>
Pipeline registry, for the grid check of the project's CRS pipeline [default: geodesy/pipelines]
--out <OUT>
Output directory (must not exist or be empty); written via a temp dir + rename
--allow-grid-absent <ALLOW_GRID_ABSENT>
Glob of pipeline ids whose absent grids are a WARNING instead of BLOCKING (e.g. 'ee.*')
--allow-unverified-profile
Accept a `production = false` profile (artifacts are marked PROFILE NOT AUTHORITY-VERIFIED)
--record
Record the frozen package in closeout_packages / export_artifacts (needs the database)
--created-by <CREATED_BY>
User (uuid or e-mail, same organisation as the project) recorded as created_by
-h, --help
Print help
Writes the closeout package into --out: the drawings, data files and closeout book, package.json, the raw evidence and a ZIP of all of it with its manifest. The same project and freeze instant always give the same bytes. With --record, the package is also recorded in the database; recording the same package again changes nothing, and a different one with the same freeze instant is refused (FROZEN_PACKAGE_CHANGED). Codes: the Packages and exports group, the grid codes and TRACE_FAIL.
asbuilt sync
Offline sync (M3): inspect the server's op state
Usage: asbuilt sync <COMMAND>
Commands:
pending What needs a person: ops stuck in the edge inbox, ops rejected because of their user, ops PENDING longer than N days (with their reason or hold), projects whose last replay was slow, and findings about ops
enable Enable sync for a project: store its starting point (the network as it is now, its stored OTDR traces included). From then on every change goes through ops; running it again changes nothing
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
asbuilt sync pending
What needs a person: ops stuck in the edge inbox, ops rejected because of their user, ops PENDING longer than N days (with their reason or hold), projects whose last replay was slow, and findings about ops
Usage: asbuilt sync pending [OPTIONS] --database-url <DATABASE_URL>
Options:
--database-url <DATABASE_URL>
[env: DATABASE_URL=]
--older-than-days <OLDER_THAN_DAYS>
List ops pending for more than this many days [default: 7]
--slow-replay-ms <SLOW_REPLAY_MS>
List projects whose last replay took longer than this (ms) [default: 1000]
--json
-h, --help
Print help
Lists what the office should follow up: ops that have been PENDING for longer than --older-than-days, with their reason (MISSING_REFERENCE or a hold reason); projects whose last replay was slow; and findings such as TRACE_SUMMARY_MISMATCH. Reads only.
asbuilt sync enable
Enable sync for a project: store its starting point (the network as it is now, its stored OTDR traces included). From then on every change goes through ops; running it again changes nothing
Usage: asbuilt sync enable --database-url <DATABASE_URL> --project <PROJECT>
Options:
--database-url <DATABASE_URL> [env: DATABASE_URL=]
--project <PROJECT> Project id or name
-h, --help Print help
Turns on offline sync for a project. The project as it is now (including its stored traces) becomes the starting point; from then on every change arrives as an op. Running it again changes nothing.
asbuilt worker
The sync worker (M3): pull job messages from the queue and apply them to PostGIS
Usage: asbuilt worker <COMMAND>
Commands:
run Pull → apply → ack after commit (plan 04 T23). The queue base URL and token come from the environment only (ASBUILT_QUEUE_BASE, ASBUILT_QUEUE_TOKEN), never from arguments
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
asbuilt worker run
Pull → apply → ack after commit (plan 04 T23). The queue base URL and token come from the environment only (ASBUILT_QUEUE_BASE, ASBUILT_QUEUE_TOKEN), never from arguments
Usage: asbuilt worker run [OPTIONS] --database-url <DATABASE_URL>
Options:
--database-url <DATABASE_URL>
[env: DATABASE_URL=]
--registry <REGISTRY>
Pipeline registry (geodesy/pipelines) [default: geodesy/pipelines]
--batch-size <BATCH_SIZE>
[default: 10]
--visibility-timeout-ms <VISIBILITY_TIMEOUT_MS>
[default: 300000]
--max-snapshot-mib <MAX_SNAPSHOT_MIB>
Largest fold snapshot to write (MiB); over it the apply fails and the message is retried [default: 64]
--once
One pull/apply/ack cycle, print its stats as JSON, exit
-h, --help
Print help
Runs on the server. It takes the ops that arrived from the field from the queue, applies them to the database and confirms each message only after it is stored. The queue address and its token are read from the environment only (ASBUILT_QUEUE_BASE, ASBUILT_QUEUE_TOKEN), never from the command line.