Skip to main content
The CLI binary is syscall. Recording requires privilege; every inspection, analysis, verification, and export command is read-only and unprivileged.

Usage

Global options may appear before or after the subcommand because they are propagated.

Global options

The default database is ~/.local/share/syscall/syscall.db.

Commands

info

Reports the platform, kernel, BTF, tracefs, tracepoint visibility, effective privilege, unprivileged BPF setting, and selected database path. It does not load BPF or modify the host.

record

The -- separator is required. The target is executed directly, not through a shell.
Scope controls userspace admission, not kernel visibility. See Record a session.

Record exit codes

sessions

Sessions are listed newest first with status, scope, time, event count, and duration.

inspect

Shows session metadata, arguments as recorded, scope, status, termination state, event counts, collection counters, loss counters, and observed processes. A missing session is an error, not an empty result.

events

Valid event types:
Unknown or uncollected types are rejected.

processes

Lists process instances derived from recorded events, including canonical identity, PID, command evidence, parent linkage when resolved, first and last observation, event count, exit observation, and unresolved flags.

tree

Renders recorded process relationships by process-instance identity. Ambiguous PID-reuse matches are left unresolved, missing parents are marked, and cycles are reported.

timeline

Ordering is timestamp_ns ASC, monotonic_ns ASC, id ASC.

files

Paths are raw openat arguments and may be relative or truncated. See Investigate a session.

connections

A successful connect means the syscall returned 0. It does not prove an established session, TCP or UDP, reachability, or data transfer.

stats

Reports duration, process-instance count, event counts, collection and loss counters, unresolved identity count when available, and session termination state.

analyze

Severity: informational (or info), low, medium, high, critical. Confidence: low, medium, high. Rule IDs:
--output truncates an existing file and sets mode 0600. It does not imply --json; the text or JSON format follows the other flags.

verify

Read-only session verification. It never migrates, repairs, or rewrites the database.

export

The destination directory must exist. The package is written atomically with mode 0600. Existing files are not replaced without --force.

verify-export

Verifies the package format, manifest entries, byte lengths, and SHA-256 hashes without modifying the file.

Time inputs

--from and --to accept:
  • Integer nanoseconds since the Unix epoch.
  • RFC3339 UTC timestamps ending in Z or z, such as 2026-11-10T12:34:56Z or 2026-11-10T12:34:56.123456789Z.
If both bounds are supplied, --from must be less than or equal to --to.

Output and errors

  • Text output is intended for people and escapes control characters in untrusted fields.
  • JSON output is valid UTF-8 and preserves nulls for unavailable values.
  • Diagnostics go to stderr; data goes to stdout.
  • Input, schema, and read failures return non-zero and do not modify evidence.
  • Read-only commands never migrate or repair a database.
For command workflows, see Record, Investigate, Analyze, Verify, and Export.