CLI Companion

The oxideterm CLI provides headless inspection, automation, CI checks, migration, and recovery for OxideTerm data. It is a standalone Rust binary that links the same domain crates used by the native desktop app and reads the same persisted stores directly.

The desktop app does not need to be running for normal CLI management commands. There is no CLI server, local RPC protocol, or socket connection. The ssh command is the exception: it intentionally launches a temporary SSH terminal in the native GUI.

Installation

Release bundles include the CLI binary. Open Settings → General → CLI Companion and select Install. The app installs:

macOS/Linux: ~/.local/bin/oxideterm
Windows: %LOCALAPPDATA%\OxideTerm\bin\oxideterm.exe

You can also build it directly:

cargo build --release -p oxideterm-cli

Global Options

Use another data directory or named profile when required:

oxideterm --config-dir <path> <command>
oxideterm --profile <name> <command>
OXIDETERM_CONFIG_DIR=<path> oxideterm <command>

Most commands support human-readable output and machine-readable JSON through --json or --format json. Use doctor --strict or a command-specific --strict option when warnings should fail CI.

State-changing commands use explicit safety controls:

Option	Purpose
`--dry-run`	Show the planned change without writing
`--yes`	Confirm a real write
`--json` / `--format json`	Return structured output for scripts

Diagnostics

oxideterm paths --json
oxideterm diagnose --json
oxideterm doctor --strict
oxideterm report --json

Use report --bundle <path> to create a redacted support bundle. Review the bundle before sharing it.

Settings

oxideterm settings validate --strict
oxideterm settings sections --json
oxideterm settings get ai.providers --json
oxideterm settings set terminal.fontSize 14 --dry-run
oxideterm settings export --section appearance --json
oxideterm settings diff ./settings-snapshot.json --section appearance

set and unset update existing JSON paths. Preview writes with --dry-run, then repeat with --yes when the plan is correct.

Connections and Forwards

oxideterm connections list
oxideterm connections search prod --json
oxideterm connections create --name prod --host example.internal --user deploy --port 22 --dry-run
oxideterm connections rename prod production --yes
oxideterm connections validate --strict
oxideterm connections export --format raw-safe --json

oxideterm forwards list --json
oxideterm forwards validate --strict

For passwords and passphrases, prefer stdin or environment options such as --password-stdin, --password-env, --passphrase-stdin, and --passphrase-env. Do not put secret values directly in shell arguments.

Backups and Restore

oxideterm backup create --output ./oxideterm-backup.json --json
oxideterm backup inspect ./oxideterm-backup.json --summary
oxideterm backup restore ./oxideterm-backup.json --section settings --dry-run --json

Review restore plans before confirming them with --yes.

Cloud Sync

oxideterm cloud-sync status --json
oxideterm cloud-sync diff --dirty-only --format table
oxideterm cloud-sync backend webdav configure --endpoint https://example.invalid/sync --dry-run
oxideterm cloud-sync push --dry-run --json
oxideterm cloud-sync pull --dry-run --json
oxideterm cloud-sync apply --from remote --strategy merge --dry-run
oxideterm cloud-sync secrets status --json

Cloud-sync secret commands report hints or status rather than secret values. Use stdin or environment variables when setting credentials.

Batch Plans

Batch plans combine settings, connection snapshots, and cloud-sync configuration into one reviewed operation:

oxideterm batch apply ./plan.json --dry-run
oxideterm batch apply ./plan.json --yes --json

Command Surface

Command	Purpose
`settings`	Read, validate, diff, import, export, and edit settings
`connections`	Inspect and manage saved SSH connections and groups
`ssh`	Open a temporary SSH terminal in the native desktop app
`forwards`	Inspect and manage saved local, remote, and dynamic forwards
`quick-commands`	Inspect and manage terminal Quick Commands
`plugins`	Inspect plugin state and manage plugin settings
`portable`	Inspect and manage the portable runtime keystore
`secrets`	Inspect hints and manage keychain-backed secrets without printing values
`oxide`	Validate, compare, import, and export encrypted `.oxide` bundles
`cloud-sync`	Configure and operate cloud sync, conflicts, history, and rollback state
`paths`	Print resolved configuration and data paths
`diagnose`	Print a read-only diagnostics snapshot
`doctor`	Run health checks for settings, connections, and cloud sync
`backup`	Preview, create, inspect, verify, diff, and restore backups
`batch`	Review and apply multi-step JSON plans
`report`	Generate a redacted support report or bundle
`completion`	Generate, locate, or install shell completion scripts
`errors`	List stable machine-readable CLI error codes

Run oxideterm --help or oxideterm <command> --help for the exact options in your installed version.

Shell Completion

oxideterm completion zsh > ~/.zfunc/_oxideterm
oxideterm completion path zsh
oxideterm completion install zsh

Completion generation supports Bash, Elvish, Fish, PowerShell, and Zsh. Use --force with completion install only when replacing an existing generated completion file.

Automation Guidance

Select the intended profile explicitly in scheduled jobs.
Prefer JSON output and stable CLI error codes for scripts.
Run validation and dry-run commands before writes.
Keep secrets out of command history and logs.
Do not assume the GUI is running; management commands are designed to operate headlessly.