omnyserver_cli library

Classes

AiCliCommand: omnyserver ai … — configure the AI provider the Hub uses to proxy :ai (and :ide) requests for web clients.
AiConfigCommand: omnyserver ai config
AiShowCommand: omnyserver ai show
AiTestCommand: omnyserver ai test
Alert: A rule currently breached by a node.
AlertRaised: A rule became breached by a node.
AlertResolved: A rule stopped being breached.
AlertRule: A condition worth being told about.
AlertsCommand: omnyserver alerts
ApiResponse: A raw HTTP response: the status and the undecoded body.
ApiTransport: One HTTP round-trip, abstracted away from dart:io.
AuditCommand: omnyserver audit
AuditEntry: An immutable record of a security- or operationally-relevant action, for the audit trail (who did what, to which target, with what outcome).
AuditRepository: Persists the audit trail.
AuthChallenge: Hub → peer: a nonce the peer must sign (public-key auth) and echo.
Authenticator: Verifies a Credential and resolves the authenticated Principal.
AuthFail: Hub → peer: authentication failed.
AuthOk: Hub → peer: authentication succeeded.
Authorizer: Decides whether an authenticated Principal may perform an action.
AuthSubmit: Peer → Hub: the credential answering an AuthChallenge.
Blueprint: What a server should be.
BlueprintApplied: A blueprint was applied to a node.
BlueprintApplyCommand: omnyserver blueprint apply <node>
BlueprintApplyRequest: Hub → node: make it so.
BlueprintApplyResult: Node → Hub: what the apply did.
BlueprintAssignCommand: omnyserver blueprint assign <id> <node>
BlueprintCommand: omnyserver blueprint …
BlueprintDeleteCommand: omnyserver blueprint delete <id>
BlueprintFile: Reads a blueprint from a file, in whichever format it was written in.
BlueprintId: Identity of a blueprint (the declaration of what a server should be).
BlueprintListCommand: omnyserver blueprint list
BlueprintPlanCommand: omnyserver blueprint plan <node>
BlueprintPlanRequest: Hub → node: work out what applying this blueprint would change.
BlueprintPlanResult: Node → Hub: what the node would have to change, or did.
BlueprintRepository: Persists Blueprints.
BlueprintResolvedCommand: omnyserver blueprint resolved <id>
BlueprintSaveCommand: omnyserver blueprint save <file.yaml|file.json>
BlueprintShowCommand: omnyserver blueprint show <id>
BlueprintSource: The bytes a human actually wrote.
BlueprintUnassignCommand: omnyserver blueprint unassign <node>
BroadcastEventBus: The default in-process EventBus, backed by a broadcast stream.
Capability: A single detected capability of a node, optionally with a version and free-form details (e.g. the GPU model for cuda).
CapabilityDetector: Probes the host for a single capability, returning it if present.
CertCommand: omnyserver cert …
CertGenCommand: omnyserver cert gen
ChallengeMinter: Mints the single-use nonces the Hub challenges peers with.
Clock: Time source used throughout OmnyServer so tests can fix now.
CommandRequest: Hub → node: run a shell command.
CommandResult: Node → Hub: the result of a CommandRequest.
ControlMessage: Base type for the JSON messages exchanged during the OmnyServer handshake — the challenge/response that runs on a freshly-opened control connection, before the omnyhub node protocol takes over.
ControlMessageCodec: Encodes handshake ControlMessages to and from the JSON envelope {"type": <type>, ...fields}, carried as WebSocket text frames.
ConvergeResult: What converging a node came to.
CpuInfo: CPU utilisation snapshot for a node.
Credential: A credential presented by a connecting party (client or node) during the authentication handshake.
CurrentState: The observed configuration of a node: what it currently advertises.
DesiredState: What the Hub wants a node to be.
DesiredStateRepository: Persists the state each node is supposed to be in.
Drift: How far a node has drifted from what it was declared to be — the wire form of a Reconciliation.
Ed25519PublicKey: An Ed25519 public key, used to identify users and nodes in an authorized_keys-style trust store. Equality is by key bytes.
ErrorCodes: Stable, machine-readable error codes carried in error control messages and surfaced on OmnyServerExceptions.
EventBus: A publish/subscribe bus for OmnyEvents.
EventsCommand: omnyserver events
Formula: An operational procedure that manages a piece of software on a node (install / update / start / stop / restart / uninstall / verify).
FormulaCommand: omnyserver formula …
FormulaContext: Ambient context handed to a Formula action: the host platform, an optional pinned target version, free-form parameters, a clock and a log sink for streaming progress.
FormulaFinished: A formula run finished on a node.
FormulaId: Identity of a formula (an operational procedure such as docker or dart).
FormulaListCommand: omnyserver formula list
FormulaRepository: Persists FormulaSpecs (formula catalogue).
FormulaResult: The structured outcome of running a single formula action.
FormulaRun: Hub → node: run a formula action.
FormulaRunCommand: omnyserver formula run <formula> <node>
FormulaRunResult: Node → Hub: the final result of a FormulaRun.
FormulaSpec: Declarative metadata describing a formula: its identity, the platforms it supports, the actions it implements and an optional target version.
FormulaStarted: A formula run started on a node.
FormulaStatusReport: One formula's answer about itself, on one node.
FormulaStatusRequest: Hub → node: report the state of the formulas this node carries.
FormulaStatusResult: Node → Hub: what each formula found when it looked at itself.
Grant: A credential the Hub has issued: who it is for, what it may do, and the fingerprint of the token that proves it.
GrantAddCommand: omnyserver grant add <principal> --role operator
GrantCommand: omnyserver grant …
GrantListCommand: omnyserver grant list
GrantRepository: Persists the credentials the Hub has issued.
GrantRevokeCommand: omnyserver grant revoke <id>
HandshakeChannel: A ControlMessage-typed view over omnyhub's HandshakeConnection.
Heartbeat: A liveness signal a node sends to the Hub at a regular interval, optionally carrying a fresh NodeStatus snapshot.
HeartbeatReceived: A heartbeat was received from a node.
Hello: First message a peer sends after connecting: announces role and protocol.
HubApiClient: A thin REST client for the Hub HTTP API, used by the CLI's operational commands — and by the web dashboard — so both exercise exactly the same public API surface as any other client.
HubCommand: omnyserver hub …
HubMetricsCommand: omnyserver hub metrics
HubStartCommand: omnyserver hub start
Identity: Who the Hub says you are.
IdGenerator: Generates opaque, unique identifiers (session ids, audit ids, request ids).
IoApiTransport: The VM transport: dart:io's HttpClient.
IssuedGrant: A credential, and the one and only time its token is readable.
Json: Manual JSON read helpers shared by control-message and entity decoders.
Ledger: What this system put on this machine.
LedgerEntry: One resource the node has been told to manage, and how it came to be there.
LogBatch: Node → Hub: a batch of log lines, pushed one-way.
LogLine: One line a node reported, stamped with when the Hub received it.
MemoryInfo: Memory utilisation snapshot for a node (bytes).
MetricPoint: One node's resource usage at an instant — the chartable projection of a NodeStatus.
MetricRepository: Persists historical metric samples for nodes.
MetricSample: A persisted, timestamped metric sample for a node.
NodeCapabilities: The set of capabilities a node advertises, keyed by capability name.
NodeCapabilitiesCommand: omnyserver node capabilities <id>
NodeCommand: omnyserver node …
NodeConnected: A node connected and authenticated to the Hub.
NodeControl: Hub → node: a node-level control request (restart / shutdown / update).
NodeDescriptor: The Hub's view of a registered node: its identity, platform, advertised capabilities, operator labels and live online flag.
NodeDisconnected: A node disconnected from the Hub.
NodeId: Stable identity of a node, used by the Hub and clients to address it (instead of a host:port). Equality is by value.
NodeLogsCommand: omnyserver node logs <id>
NodeMetricsCommand: omnyserver node metrics <id>
NodeRepository: Persists the Hub's view of registered nodes.
NodeRestartCommand: omnyserver node restart <id>
NodesCommand: omnyserver nodes …
NodeShowCommand: omnyserver node show <id>
NodeShutdownCommand: omnyserver node shutdown <id>
NodesListCommand: omnyserver nodes list
NodeStartCommand: omnyserver node start
NodeStatus: A point-in-time live snapshot of a node's health and resource utilisation.
NodeStatusCommand: omnyserver node status <id>
NodeUpdateCommand: omnyserver node update <id>
NodeUpdated: A node was updated (OS, package or agent).
OmnyEvent: Base type for every event emitted on the Hub's EventBus.
OmnyServerHome: Resolves the OmnyServer home directory (~/.omnyserver by default), where identity, credentials and local state live.
OmnyUid: A globally-unique, content-derived identity for a node or hub.
Operation: Something the Hub is doing to a node, that takes long enough to be worth a name.
OperationAck: A generic acknowledgement for a request that has no richer result type.
OperationFinished: A long-running operation finished.
Operations: The operations the Hub invokes on a node, and the results it gets back.
OperationStarted: A long-running operation was dispatched to a node.
OpsCommand: omnyserver ops …
OpsListCommand: omnyserver ops list
OpsShowCommand: omnyserver ops show <id>
PlatformInfo: Static facts about a node's host operating system and agent build, reported once at registration (and refreshed on reconnect).
Preset: A named desired-configuration bundle: an ordered list of formula steps that move a server toward a target state. Presets are designed to be idempotent.
PresetApplied: A preset was applied to a node.
PresetApply: Hub → node: apply a preset (a bundle of formula steps).
PresetApplyCommand: omnyserver preset apply <preset.json> <node>
PresetApplyResult: Node → Hub: the result of applying a preset.
PresetCommand: omnyserver preset …
PresetDeleteCommand: omnyserver preset delete <id>
PresetId: Identity of a preset (a named desired-configuration bundle of formulas).
PresetListCommand: omnyserver preset list
PresetRepository: Persists Presets.
PresetSaveCommand: omnyserver preset save <preset.json>
PresetShowCommand: omnyserver preset show <id>
PresetStep: A reference to a formula within a preset: which formula, which action to drive, and an optional pinned version.
Principal: An authenticated identity, with the roles it holds. Used by the Hub to make authorization decisions.
PrincipalId: Identity of an authenticated principal (a user account or a node account).
ProcessInfo: A running process snapshot and its resource consumption.
ProtocolErrorMessage: Either side: a protocol-level error raised during the handshake.
ProtocolVersion: The wire protocol version negotiated in the Hello handshake.
Reconciliation: The plan produced by reconciling a desired state against the current state: the ordered steps that still need to run to converge.
ResolvedBlueprint: A blueprint with its includes flattened, variables substituted and resources ordered — everything a node needs, and nothing it has to work out.
ResolvedResource: A resource after resolution, and where it came from.
Resource: One declared thing a blueprint wants on a node.
ResourceChange: One resource's line in a plan, and afterwards its line in a report.
ResourceId: What a resource is called: its type, and its name within that type.
ResourceProvider: Knows how to read and write one kind of resource on a node.
ResourceState: What a provider found when it looked at one resource on a node.
Rollbackable: Optional mixin for formulas that can roll back a failed action.
ServiceCommand: omnyserver service …
ServiceControl: Hub → node: control an OS service.
ServiceControlResult: Node → Hub: the result of a ServiceControl.
ServiceDescriptor: Describes an OS-level service managed by OmnyServer (hub or agent), abstracting over systemd / launchd / Windows Service Manager.
ServiceInfoCommand: omnyserver service info <hub|node>
ServiceInstallCommand: omnyserver service install <hub|node>
ServiceReconfigureCommand: omnyserver service reconfigure <hub|node>
ServiceReinstallCommand: omnyserver service reinstall <hub|node>
ServiceRestartCommand: omnyserver service restart <hub|node>
ServiceStartCommand: omnyserver service start <hub|node>
ServiceStatusCommand: omnyserver service status <hub|node>
ServiceStopCommand: omnyserver service stop <hub|node>
ServiceUninstallCommand: omnyserver service uninstall <hub|node>
StateClearCommand: omnyserver state clear <node>
StateCommand: omnyserver state …
StateDiffCommand: omnyserver state diff [<node>] [--label …]
StateReconcileCommand: omnyserver state reconcile [<node>] [--label …]
StateReconciler: Computes the Reconciliation needed to move a node from its current state toward a desired state.
StateSetCommand: omnyserver state set <preset.json> [<node>] [--label …]
StateShowCommand: omnyserver state show <node>
StatusReport: Node → Hub: a live status snapshot, pushed one-way.
StorageDevice: A single storage device / mount point snapshot (bytes).
SystemClock: The default Clock, backed by the system wall clock (UTC).
UuidGenerator: The default IdGenerator, backed by random (v4) UUIDs.
ValidationResult: The result of validating a formula's managed software.
WhoamiCommand: omnyserver whoami

Enums

AlertMetric: What an AlertRule watches.
AuditOutcome: The outcome of an audited operation.
BlueprintFormat: The format a blueprint was written in.
CapabilityKind: The well-known kinds of capability a node can advertise.
ChangeKind: What a plan proposes to do about one resource, or what an apply did.
Ensure: What a resource should be, as opposed to what should be done to it.
FormulaAction: The operational steps a Formula supports.
FormulaStatus: What a formula found when it looked at the thing it manages.
OperationStatus: Where an Operation has got to.
PeerRole: The role a connecting party announces in its Hello.
ServiceStatus: The lifecycle state of an OS-managed service.

Constants

aiConfigHelp → const String: The help text for --ai-config, shared with the service parser.
ephemeralHelp → const String: The help text for --ephemeral, shared with the service parser.
hubDataDirHelp → const String: The help text for the Hub's --data-dir, shared with the service parser.
omnyServerVersion → const String: The canonical OmnyServer package version (kept in sync with pubspec.yaml).
servicePackage → const String: The package name dart_service_manager records these services under.
serviceRoles → const Set<String>: The installable roles. The role is a positional argument.

Properties

serviceStoragePaths ↔ StoragePaths?: Where the service registry and the compiled service binaries live.
getter/setter pair

Functions

addHubStartOptions(ArgParser parser, {bool includeShellPath = true, bool includeDataDir = true}) → void: Adds the hub start options to parser.
addNodeStartOptions(ArgParser parser, {bool includeShellPath = true}) → void: Adds the node start options to parser.
addServiceRoleOptions(ArgParser parser) → void: Registers the union of the Hub and Node start options.
blueprintFormatOf(String path) → BlueprintFormat: The format a file extension names.
buildRunner() → CommandRunner<void>: Builds the OmnyServer CommandRunner with every command wired to the public runtimes and the Hub HTTP API.
decodeChallenge(String nonce) → Uint8List: Decodes a wire nonce back to its raw bytes.
defaultApiTransport() → ApiTransport: The transport HubApiClient uses when none is injected, on the VM.
emitFlag(List<String> out, String name, bool value) → void: A non-negatable flag: emitted when set, absent otherwise.
emitMultiOption(List<String> out, String name, List<String> values) → void: Appends --name value once per entry of a multi-option.
emitNegatableFlag(List<String> out, String name, bool value) → void: A negatable flag, emitted explicitly in both directions.
emitOption(List<String> out, String name, Object? value) → void: Appends --name value to out when value is non-empty.
emitPathOption(List<String> out, String name, Object? value) → void: Like emitOption, but absolutized — so the baked-in service command finds the file regardless of the service's working directory.
encodeChallenge(Uint8List challenge) → String: Encodes challenge for the wire.
hubDataDir(String root) → String: The Hub's persistence directory inside the data root: the fleet data (nodes, audit, metrics, desired state, issued grants) lives under hub/, alongside — not mixed into — the credentials and identity at the root.
omnyServerAiConfigPath([String? explicit]) → String: The AI config file the Hub proxies from, and ai config writes to.
parseBlueprint(String text, BlueprintFormat format, {String origin = 'the blueprint'}) → Blueprint: Parses a blueprint written in format.
rejectForeignOptions(String role, ArgResults args) → void: Rejects options belonging to the other role.
requireRole(ArgResults args) → String: Reads and validates the hub|node role positional from args.
resolveDataDir(ArgResults args, {bool systemScope = false}) → String?: The data root: the directory holding everything this installation keeps — credentials and identity, plus (for a Hub) the fleet data underneath it.
resolveHubDataDir(ArgResults args) → String?: The directory hub start persists the fleet in.
runOmnyServerCli(List<String> args) → Future<void>: Runs the CLI with args, handling usage and CLI errors with exit codes.
runService(Future<void> action()) → Future<void>: Runs a dart_service_manager action, translating its exceptions into the CLI's CliError for a clean, stack-trace-free message.
serviceDescriptor(String role, ArgResults args) → ServiceDescriptor: Builds the descriptor that installs this omnyserver executable to run omnyserver <role> start … with the flags captured from args.
serviceStartArgs(String role, ArgResults args) → List<String>: Reconstructs the omnyserver <role> start … argument vector from args, absolutizing filesystem paths so the baked-in command works from any directory.
systemDataDir() → String: The machine-wide data root for a --system service: /var/lib/omnyserver on POSIX, %ProgramData%\omnyserver on Windows (which has no /var/lib).
validateHubTls(ArgResults args) → String?: Validates the Hub's TLS source — exactly one of --tls-dir or (--cert + --key), never neither (the Hub has no insecure mode). Returns the trimmed --tls-dir in directory mode, otherwise null.
validateNodeStartArgs(ArgResults args) → void: Validates that args carries what a Node agent needs to start.

Exceptions / Errors

AuthException: Authentication failed: credentials missing, malformed or rejected.
AuthorizationException: The authenticated principal is not permitted to perform the action.
CliError: A user-facing CLI error (printed without a stack trace).
HubApiException: Thrown when a Hub API request fails.
NodeUnavailableException: The requested node is unknown or offline.
NotFoundException: A requested resource (formula, preset, node) was not found.
OmnyServerException: Base type for every expected, classified failure raised by OmnyServer.
OmnyServerTimeoutException: An operation exceeded its deadline.
OperationException: An operation (command, formula, preset) failed during execution.
ProtocolException: A frame could not be decoded, or a message violated the protocol.
StorageException: A persistence backend failed to read or write.
TransportException: The underlying transport failed or closed unexpectedly.

omnyserver_cli library

Classes

Enums

Constants

Properties

Functions

Exceptions / Errors

omnyserver package

omnyserver_cli library