reference
Reference
Commands, configuration, exit codes, environment, service modules and development, for omni 0.3.0.
Commands
Every command takes --json (machine-readable envelopes), --target NAME and --config PATH. omni command --help lists the rest.
| Command | Main options | Does |
|---|---|---|
send cmd | --adb --serial --dry-run --relay --device --token --daemon --require-delivery | One command: text, key, combo, scroll or event |
cast | --frame line|char|ndjson --adb --serial --dry-run --daemon --token | Stream standard input |
run file|- | the targets of send, and --dry-run | A macro file with wait delays |
serve | --listen (default 127.0.0.1:8765) --token | The relay hub |
daemon | --listen (default 127.0.0.1:8766) --backend --relay --device --token --dry-run --print-service --install-service --user | Inject locally, optionally registered to a hub |
listen, get | --daemon (default 127.0.0.1:8766) --events --token | Stream, or take one, received command |
devices | --relay --token --json | Device ids on a hub |
config | --target --example --schema | Resolved targets, a starter file, or the JSON Schema |
doctor | --probe --json | Read-only health checks |
status, update | Version and capabilities; self-update | |
mcp stdio, mcp tools | The MCP server, or its tool list | |
completions shell | bash, zsh, fish, powershell or elvish |
Configuration
Read from --config, else $OMNI_CONFIG, else ~/.config/omni/config.yaml. default_target names the target used when --target is omitted. Each entry under targets has an optional description and exactly one of transport or group (a list of other target names).
transport.type | Fields | Reaches |
|---|---|---|
adb-broadcast | serial, sender_package (both optional) | The omni keyboard on an adb-attached Android device |
termux | The keyboard on the same device, when omni runs on Android | |
tcp | host, port | A listener that accepts NDJSON over TCP, such as an Android command server or a desktop daemon |
relay | url, device, token_env | A device connected to a relay hub; token_env names the variable that holds the token |
Exit codes
| Code | Means |
|---|---|
| 0 | Success, including warnings from doctor |
| 1 | A delivery or check failed |
| 2 | Invalid usage or an unparseable command |
| 3 | With --require-delivery: the relay confirmed no device received the cast |
Environment
| Variable | Used for |
|---|---|
OMNI_CONFIG | The configuration file |
OMNI_RELAY_TOKEN | The shared relay and daemon token, when --token is not given |
FEEDBACK_WEBHOOK_BASE_URL, FEEDBACK_WEBHOOK_URL, FEEDBACK_WEBHOOK_TOKEN_ENV, FEEDBACK_COMPONENT, FEEDBACK_PROJECT | Feedback routing (see Agents) |
COMPLETE | Set by a shell's dynamic completer |
Service modules
The flake exports nixosModules.omni (a systemd user service) and darwinModules.omni (a launchd agent). The daemon and the hub are independent, so a machine can be either or both.
imports = [ inputs.omni-cli.nixosModules.omni ];services.omni = { enable = true; backend = "auto"; relay = "hub.example:8765"; # also register with a hub device = "quill"; tokenFile = "/run/secrets/omni-relay-token"; serve.enable = false; # true to run a hub here};| Option | Default | Means |
|---|---|---|
enable | false | Run omni daemon |
listen | 127.0.0.1:8766 | The daemon's address for senders and subscribers |
backend | auto | auto, xdotool, wtype, ydotool, osascript or log |
relay, device | null | Also register with a hub, as this device id (default: the host name) |
tokenFile | null | A file holding the token, exported as OMNI_RELAY_TOKEN to the daemon and the hub |
tokenWaitSeconds | 60 | How long to wait at boot for the token file to appear |
token | null | An inline token; readable in the Nix store, so prefer tokenFile |
configFile | %h/.config/omni/config.yaml | The configuration file |
preferLocalBinary | true | Use a self-updated ~/.local/bin/omni when present |
extraArgs | [] | Appended to omni daemon |
serve.enable | false | Run the hub, omni serve |
serve.listen | 127.0.0.1:8765 | The hub's address; set a reachable one for devices |
serve.extraArgs | [] | Appended to omni serve |
Development
| Command | Does |
|---|---|
nix develop | A shell with the pinned Rust toolchain |
cargo test --workspace | CLI and SDK unit tests |
nix run .#preflight | Format, Clippy with warnings as errors, and tests, as CI runs them |
nix run .#test | Build and smoke-test the CLI |
nix run .#relay-test | An end-to-end relay round trip: hub, daemon and sender |
nix run .#doctor | Check the repository's conventions |
nix run .#release -- patch | Cut a release tag; assets build on self-hosted runners |
The Rust API documentation is generated at publish time and served under api/. This site is built from site/ by scripts/site/build.py and checked by scripts/check-site.py.