tailapp prints JSON to standard output. Errors are written as command errors
and return a nonzero exit status. Except for init, serve, and
ingest-fixture transport, commands are clients of the resident engine's
owner-only Unix socket.
tailapp --help summarizes the shortest init, serve, install, and query path;
tailapp apps --help lists the one-shot install and lower-level lifecycle.
TAILAPP_HOME selects the engine home. If unset, tailapp uses the stable,
documented per-user location ~/.local/share/tailapp on every supported
platform. Set it explicitly when the resident and harness-launched MCP
processes must share a non-default engine.
export TAILAPP_HOME="$HOME/.local/share/tailapp"Creates the protected engine home and projection/temp directories. It is safe to call again for the same home.
Installs requested missing built-in bundles through the running resident's
create-only control operation. The default requests all five bundles;
--bundles accepts a comma-separated subset or none. Existing Tailapps are
reported as already_present and are never overwritten, reset, or activated.
The JSON result contains home, requested, installed, and
already_present.
The default never prompts. --interactive asks for confirmation only through
a readable, writable /dev/tty; it refuses in non-interactive environments.
Run tailapp serve first, or use the signed release installer to create the
resident service before this bundle-only step.
Runs the single resident engine, control socket, projection worker, and
OTLP/HTTP receiver. The default receiver is 127.0.0.1:4318. The host must be
an explicit IPv4 or IPv6 loopback address; names such as localhost and
non-loopback interfaces are refused. Port 0 chooses an ephemeral port.
On startup it prints the home, control socket, and actual receiver URL and
writes owner-only engine.json. Stop it with SIGINT or SIGTERM.
Returns the runtime profile, ingestion readiness, inbox statistics, projection
frontiers, and unavailable projections. This is the same engine status model
returned by apps status and tailapp_status.
Returns the versioned operational metrics snapshot. JSON is the default and
only format; --json makes that choice explicit for scripts. Process counters
reset when the resident restarts, while each Tailapp's durable projection
totals survive a restart. See the runtime metrics reference for
field definitions, fixed histogram boundaries, privacy constraints, and reset
semantics.
Returns the 16 most recent records that the named Tailapp's normalizer declared
ineffective. Samples are held only in resident memory, disappear on restart or
activation, and are ordered oldest to newest. Each sample includes its delivery
position, active revision, signal, event name, source, record timestamps and
IDs when present, received_at_unix_nano, content digest, and the actual
canonical record JSON. The receipt timestamp is always present and identifies
when the resident accepted the sampled record.
ineffective_records is the durable total since initial activation or reset,
available_records is the number represented by the current memory buffer, and
unavailable_records makes restart, activation, and ring-eviction gaps explicit.
The last value is zero only when every durable ineffective decision remains in
the buffer; it does not claim that omitted or redacted fields were observed.
A canonical record larger than 32 KiB retains only metadata, record_bytes,
and record_omitted: true. The buffer can contain sensitive prompt, tool, path,
or attribute content and is available to any process that can access the
owner-only control socket. Use the durable ineffective_records query-result
field or metrics for counting; this command is a bounded diagnostic sample,
not an event log.
Runs the MCP JSON-RPC adapter over newline-delimited stdio. It does not start
an engine; tailapp serve must already be running with the same
TAILAPP_HOME. See the MCP reference.
Posts an OTLP fixture to the URL in engine.json. This is intended for tests
and local demonstrations.
Options:
--signal logs|traces|metrics(defaultlogs)--content-type application/json|application/x-protobuf(default JSON)
Tailapp names match ^[a-z][a-z0-9-]{0,62}$.
Lists definitions with draft and optional active revision metadata.
Creates a draft. Omit --bundle for an empty custom Tailapp. The only built-in
bundle names in this release are activity-stats, agent-guard,
daily-review, session-cost, and signal-counts.
Validates a complete source set and first-activates one new Tailapp in a single idempotent control request. It is create-only and refuses an existing app name.
Install custom source from a directory:
tailapp apps install \
--idempotency-key install-signal-counts-v1 \
signal-counts tailapps/signal-countsThe directory may contain author documentation. Only application.sql and
regular, non-symlink folds/*.jsonata files become executable source.
Install a built-in bundle without a directory:
tailapp apps install --bundle agent-guard \
--idempotency-key install-agent-guard-v1 agent-guardThe concise result contains app, compiled-profile identity and contract
digests, and the active frontier. Pass --full to include the complete
compiled profile. Use the lower-level commands below for updates to an existing
app.
Returns draft metadata and all source elements. Binary JSON fields representing source bytes use standard base64 in the JSON response.
Reads FILE and puts it at source PATH using optimistic revision control.
The result contains the next draft revision; use that revision for the next
mutation. Allowed paths are application.sql and folds/*.jsonata.
Removes one draft element and returns the next draft revision. It does not alter live behavior.
Compiles the complete exact draft without activation. The result is the compiled profile: revision, runtime, event, tables, writers, reads, programs, views, exports, and storage/export digests.
Activates the exact draft at a drained delivery boundary.
Options:
--expected REV: exact draft revision--mode continue|reset(defaultcontinue)--ack-reset: required withreset
The first activation requires reset. A continue preserves current rows and
requires the same stored runtime identity and all existing writable tables to
retain their exact stored shape; new tables are allowed. A runtime change
requires an acknowledged reset even when table shapes match. A reset discards
only this Tailapp's materialized state.
Deletes a definition and detaches its projection obligations. It does not delete other Tailapps.
Returns engine status; equivalent to tailapp health.
Returns the active compiled profile. Draft-only Tailapps have no live schema.
Prints one JSON object describing this binary: semantic or development
version, VCS revision and dirty state, sanitized source URL, Go version,
operating system, and architecture. Revision and source URL are empty when the
build did not embed them. It does not contact a resident or read
TAILAPP_HOME.
A release that changes the runtime identity deliberately reopens existing
projections in an upgrade-pending state. While any active Tailapp is pending,
the OTLP receiver returns HTTP 503 with ingestion_not_ready and the resident
reports ingestion_ready: false. Existing projections remain queryable, and a
Tailapp frontier can still say complete: true: completeness describes its
stored delivery frontier, not whether intake has reopened.
The declared-input contract changes the core interface, Tailapp dialect and host orchestration identity. Recompiling the same source under the new runtime does not authorize retaining its old projection. Continuation checks the persisted runtime before any activation journal, queue detachment or projection write. A refusal preserves the old rows, frontier, identity and pending work.
- Inspect each application's current data and record its
draft_revisionwithtailapp apps get APP. Export anything needed before discarding a projection. - Put any intentional source changes using the returned draft revisions,
then run
tailapp apps validate --expected REV APP. - For each old-runtime application, explicitly accept the loss of its
materialized state with
tailapp apps activate --mode reset --ack-reset --expected REV --idempotency-key KEY APP. Reset starts a fresh projection at the current delivery boundary; it does not replay historical records. Binary installation alone performs no reset. - Repeat until
tailapp healthreportsingestion_ready: true, then resume exporters.
Within one runtime, compatible source changes can still use --mode continue.
A changed or removed existing writable table requires acknowledged reset.
The MCP equivalents use tailapp_get, tailapp_put, tailapp_validate,
tailapp_activate with the same reset acknowledgement, and tailapp_status.
tailapp query [options] --sql SQL APP
Options:
--param JSON: positional parameter; repeat up to 64 times--mount ALIAS=TAILAPP: expose another active Tailapp's exports; repeatable--expected-revision REV: fail if the active revision differs--expected-position N: fail if the interpreted frontier differs--limit N: row limit, 1 to 1000; default 256
Parameters are parsed as JSON, so quote strings as JSON strings:
tailapp query \
--sql 'SELECT session_id FROM session_progress WHERE harness = ? ORDER BY session_id' \
--param '"codex"' \
agent-guardThe result reports the active revision, delivery head, interpreted position,
durable ineffective_records count for the active projection, mounted schemas,
completeness, column metadata, rows, encoded result_bytes, and whether output
was truncated. ineffective_records counts records rejected since the
projection's initial activation or most recent reset, including across
compatible continue activations; it is independent of the
number of rows returned by the SQL statement. See the query SQL
reference.
Install, create, put, remove, activate, and delete require a printable ASCII
key of 1 to 128 characters with no leading or trailing space. Retrying the
identical operation, arguments, and key replays the original success or error.
Reusing a key for any different request returns idempotency_conflict. A key
left pending across a crash returns idempotency_in_doubt; Tailapp will not
guess whether to repeat the mutation.
Element mutations and validation use the exact draft revision. A stale value
returns revision_changed. Query expectations return frontier_changed when
the live snapshot moved.