Command Line
Last updated:
oscova is the command-line tool that ships alongside the Oscova host. It starts and stops the host, asks agents questions, and inspects almost everything the web UI shows: agents, threads, tasks, plugins, skills, MCP servers, logs, notifications, tool governance, and the egress ledger.
Install
The CLI is packaged as a .NET global tool named oscova.
dotnet tool install --global Oscova.Agents.App
Run oscova --help for the command list, oscova <command> --help for one command, and oscova doctor when something is not working.
Three separate identities
Oscova has three sign-in surfaces and they never share state.
- The browser cookie signs you in to the web UI. It never applies to a terminal.
- The CLI bearer token is created by
oscova loginand stored in~/.oscova/auth.json. Every command that talks to the host API uses it. - The local runtime control token is written to
~/.oscova/runtime.jsonwhen a host starts on this machine. Lifecycle commands (start,stop,restart) use it so you can control a local host without logging in.
oscova whoami shows all three at once, and oscova doctor explains what to run when one of them is missing.
Browser cookies and CLI bearer tokens are valid only for the current Host process. After oscova restart or another Host restart, the old token is rejected. The existing login flow removes the stale host entry and offers browser login again. The browser approval page also blocks until the user creates or unlocks their vault, or signs out.
Global options
Every command accepts these.
| Option | Meaning |
|---|---|
-H, --host <URL> |
Oscova host URL for client commands. |
--quiet |
Suppress informational output. Errors and requested data still print. |
--no-color |
Disable colour and ANSI styling. Also honoured via the NO_COLOR environment variable. |
--no-interactive |
Never prompt. Commands that would need input fail with exit code 4 instead. |
--json |
Emit machine-readable JSON on stdout instead of formatted output. |
-h, --help |
Print help for the CLI, a branch, or a command. |
-v, --version |
Print the CLI version. |
The host URL is resolved in this order: --host, the OSCOVA_HOST environment variable, the host value in ~/.oscova/cli-config.yaml, the host you last logged in to, then the default local host.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Internal failure, on the host or in the CLI. |
| 2 | Not authenticated. Run oscova login. |
| 3 | Authenticated but not allowed. |
| 4 | Usage error: a bad argument, a missing required option, or a prompt that could not be shown. |
oscova doctor is the exception: it always exits 0, because reporting a broken environment is a successful run.
The interactive gateway
Running oscova with no command opens the gateway: a chat session in your terminal. It starts the local host and signs you in if either is missing, then keeps one thread going until you leave.
A dim line above the input shows where the next message goes: the host URL, the current agent, the model, and the thread.
Inside the session, type a slash command instead of a message.
| Command | What it does |
|---|---|
/help |
List the session commands and key bindings. |
/status |
Show the target host, the CLI login, and host state. |
/agents |
Switch the current agent. |
/model |
Override the model provider for this session. |
/thread |
Switch to an existing thread. |
/new |
Start a fresh thread. |
/clear |
Clear the transcript. |
/quit |
Leave the gateway. |
These are session commands only. The shell commands documented below are a separate surface: run oscova --help outside the gateway for those.
Key bindings while typing:
| Key | What it does |
|---|---|
| Up and Down arrow | Recall earlier prompts. Prompts are stored in ~/.oscova/history. |
| Tab | Complete the highlighted slash command in the suggestion list. |
| Left, Right, Home, End | Move the caret within the line. |
| Enter | Send the message. |
| Ctrl+C | Discard what is typed. On an empty line, leave the session. |
| Ctrl+D | Leave the session from an empty line. |
Typing / opens a suggestion list filtered as you type. Up and Down move through it, and Tab accepts the highlighted entry.
When an agent needs a tool approved, the gateway shows a card with the tool name and its arguments, then asks you to allow or deny it. Shell and skill-script cards also show the execution target and full command arguments. Approving a skill script runs the whole script. Requests for input appear the same way.
Streamed replies arrive as plain text, then are redrawn with markdown styling once the reply completes. In a redirected or non-colour terminal the plain text is kept as is, so piped output stays clean.
Command reference
Host lifecycle
| Command | What it does |
|---|---|
start |
Launch the host. Add --detach to run it in the background, --port <PORT> and --host-bind <HOST> to choose where it binds. |
stop |
Stop a running host. |
restart |
Restart a running host. |
status, st |
Show host status. |
version |
Show the CLI version and, if reachable, the host version. |
doctor |
Run read-only diagnostics on the CLI, its host connection, and its credentials. |
Foreground oscova start stays attached to the terminal. Once the Host is ready, it prints Oscova is running at <URL> (pid <PID>).
When required components are missing, startup first shows each package name with a spinner and a component-count progress bar. The bar counts completed attempts, not downloaded bytes. Installed and failed results remain visible with a final summary. A failed component does not stop startup. The display closes before optional onboarding appears.
Redirected or non-interactive output, --no-color, and --no-interactive use ordinary lines instead of the live display. --quiet and --json suppress component feedback and the foreground readiness message. No installation output appears when nothing needs installing. See Plugins for default-component behavior and failure recovery.
Identity
| Command | What it does |
|---|---|
login |
Sign in this CLI to an Oscova host. |
logout |
Revoke and remove this CLI login. |
whoami |
Show CLI login and local control state. |
Chat
| Command | What it does |
|---|---|
ask [PROMPT] |
Ask an agent. Omit the prompt to read it from standard input. |
threads list |
List chat threads, newest first. |
threads show <THREAD_ID> |
Show one thread's details. |
threads messages <THREAD_ID> |
Print the messages in one thread. |
threads new |
Start a new thread and print its id. Add --agent <AGENT_ID> to pick the agent. |
threads rename <THREAD_ID> <TITLE> |
Give a thread a new title. |
threads delete <THREAD_ID> |
Delete one thread. |
threads clear |
Delete every thread. |
ask accepts --agent, --thread, --continue to resume the most recently updated thread, --model, --stream or --no-stream, --timeout <SECONDS>, and --jsonl for a stream of machine events as JSON lines.
Agents, models, plugins, and skills
| Command | What it does |
|---|---|
agents list |
List every agent with its model and source. |
models list |
List the models available to agents. |
models test <PROVIDER_ID> |
Check that a configured provider answers. |
models local |
List the local model files installed on the host. |
models available <PROVIDER_ID> |
List the models one provider offers. |
plugins list |
List installed plugins and their status. |
skills list |
List installed skills. |
skills import <FILE> |
Import a skill package from a local file. |
skills remove <SKILL_NAME> |
Uninstall a skill. |
Tasks
| Command | What it does |
|---|---|
tasks list |
List scheduled tasks. |
tasks show <TASK_ID> |
Show one task's configuration. |
tasks runs <TASK_ID> |
List a task's recent runs. --limit <N> defaults to 20. |
tasks run-show <TASK_ID> <RUN_ID> |
Show one run's result. |
tasks trigger <TASK_ID> |
Run a task now. |
tasks delete <TASK_ID> |
Delete a task. |
MCP servers
| Command | What it does |
|---|---|
mcp list |
List MCP servers and their connected tools. |
mcp add |
Register a server and connect to it. |
mcp remove <SERVER_ID> |
Remove a server. |
mcp restart <SERVER_ID> |
Reconnect one server. |
mcp reconnect |
Reconnect every server. |
mcp add needs --name, --transport http|stdio, then --endpoint <URL> for HTTP or --command <EXECUTABLE> with repeatable --arg <VALUE> for stdio. For a server that needs headers, environment variables, or a working directory, write the full JSON definition to a file and pass --file <PATH> instead.
Diagnostics and audit
| Command | What it does |
|---|---|
logs files |
List the log files on the host. |
logs read |
Read one page of log entries. Filter with --file, --level, --search, --page, --page-size. |
logs clear --file <NAME> |
Empty one log file. --file is required. There is no clear-all. |
notifications list |
List notifications, newest first. |
notifications read <ENTRY_ID> |
Mark one notification read. |
notifications read-all |
Mark every notification read. |
notifications clear |
Empty the notification inbox. |
tools list |
List governed tools with their network scope and call budget. |
egress list |
Read one page of the egress ledger. Filter with --page, --page-size, --from, --to, --kind, --source, --search. |
Tool governance is inspected here and edited in the web UI, because a policy edit sets a network scope and a call limit together and both need to be visible at once.
Environment and CLI settings
| Command | What it does |
|---|---|
environment export |
Write a passphrase-sealed backup. Requires an administrator account. |
environment restore --file <PATH> |
Restore a backup onto a fresh install and restart the host. |
config get [KEY] |
Print one CLI setting, or all of them. |
config set <KEY> <VALUE> |
Change one CLI setting. |
The CLI settings are host, default-agent-id, and default-stream, stored in ~/.oscova/cli-config.yaml.
Backups are sealed with a passphrase. Pass it with --passphrase, or leave it out and the CLI prompts for it without echoing it. Under --no-interactive or --json the passphrase must be passed explicitly, because there is nowhere to prompt.
This Export Passphrase protects the .oscb archive and is unrelated to the account's Vault Password.
Destructive commands
Anything that deletes data asks for confirmation first: threads delete, threads clear, tasks delete, skills remove, mcp remove, logs clear, notifications clear, and environment restore.
Pass --yes to skip the prompt in a script. Under --no-interactive without --yes, the command exits 4 rather than guessing.
Worked examples
Start a host in the background, then sign in:
oscova start --detach
oscova login
Ask a question and keep the conversation going:
oscova ask "what is on my calendar today"
oscova ask "and tomorrow" --continue
Run a scheduled task now and read its result:
oscova tasks list
oscova tasks trigger 4f1c9a2e-....
oscova tasks runs 4f1c9a2e-.... --limit 5
Pipe machine output into another tool:
oscova threads list --json | jq -r '.[].id'
oscova logs read --level Error --json | jq '.entries | length'
Check the environment when something is not working:
oscova doctor