oo-cli Command Reference

This page summarizes the current oo command surface from the oo-cli repository.

Global Options

Option	Purpose
--debug	Print the current log file path to stderr when the CLI exits
--lang <lang>	Override the display language for the current invocation. Supported values: en, zh
-h, --help	Show help for the current command
-V, --version	Show the CLI version, build time, and commit hash

Debug Logging

oo writes persisted structured logs to platform-specific locations:

• macOS: ~/Library/Logs/oo
• Linux: ${XDG_STATE_HOME:-~/.local/state}/oo/logs
• Windows: %LOCALAPPDATA%\\oo\\Logs

These logs cover remote API request lifecycles, browser-login callbacks, explicit update checks, settings and auth store changes, and sqlite cache activity. The CLI keeps the newest 20 log files.

Authentication

Command	Purpose
oo auth login	Start the browser login flow and save the authenticated account
oo auth logout	Remove the current account from persisted auth data
oo auth status	Show the current account and validate its API key
oo auth switch	Switch to the next saved account
oo login	Alias for oo auth login
oo logout	Alias for oo auth logout

Configuration

Command	Purpose
oo config list	List currently persisted configuration values
oo config get <key>	Read one persisted configuration value
oo config path	Print the config file path
oo config set <key> <value>	Persist one configuration value
oo config unset <key>	Remove one configuration value

Supported configuration keys:

• lang
• file.download.out_dir

Notable behavior:

• Unknown keys in the persisted settings file are ignored and logged as warnings.
• file.download.out_dir accepts any non-empty path string.
• Relative download paths resolve from the current working directory when oo file download runs.

Updates

Command	Purpose
oo install [version]	Install one oo-managed CLI release into the local managed runtime
oo update	Update the managed CLI install to the latest published release
oo upgrade	Alias for oo update
oo check-update	Check whether a newer CLI release is available

When a newer release exists, oo prints the recommended upgrade command for the current package manager.

For a first-time install, prefer the official install scripts from the oo-cli Guide. oo install [version] is mainly useful when you need the managed runtime to install or reinstall a specific CLI release.

Search And Discovery

Mixed Search

Command	Purpose
oo search <text>	Search packages and connector actions with one free-form query

Notable behavior:

• JSON output mixes package and connector results and uses kind as the discriminator.
• Connector results include authenticated and schemaPath.

Connector Discovery

Command	Purpose
oo connector search <text>	Search connector actions with free-form text
oo connector schema <serviceName>	Show the JSON schema contract for one connector action
oo connector schema refresh	Clear the local connector schema cache
oo connector run <serviceName>	Validate input data and run one connector action

Notable options for oo connector schema:

• -a, --action <action>: target action name
• --refresh: bypass cached schema data and fetch fresh data
• --json: accepted for compatibility; schema output is always JSON

Notable options for oo connector run:

• -a, --action <action>: required action name
• -d, --data <data>: inline JSON or @path to a JSON file
• --dry-run: validate the payload without executing the action
• --json: emit structured output

Package Discovery

Command	Purpose
oo packages search <text>	Search published packages with free-form intent text
oo packages info <packageSpecifier>	Show metadata for one package

<packageSpecifier> supports foo/bar, foo/bar@latest, and foo/bar@1.2.3.

Cloud Tasks

Command	Purpose
oo cloud-task run <packageSpecifier>	Validate input values and create a Cloud Task for a package block
oo cloud-task list	List cloud tasks with optional filters
oo cloud-task log <taskId>	Show paginated logs for one task
oo cloud-task result <taskId>	Show the current result for one task
oo cloud-task wait <taskId>	Poll until a task reaches a terminal state

Key details:

• oo cloud-task run requires PACKAGE_NAME@SEMVER.
• Use -b, --block-id <block-id> to choose the target block.
• Use -d, --data <data> for inline JSON or @path/to/file.json.
• --dry-run validates the request without creating a task.
• oo cloud-task wait polls every 3 seconds and accepts --timeout.

Skills

Command	Purpose
oo skills list	List bundled, registry, and local skills installed in supported agent hosts
oo skills search <text>	Search published skills
oo skills sync	Sync registry skills
oo skills preflight --agent <agent>	Check local skill editing prerequisites for one supported host
oo skills init <name>	Initialize a local skill in a supported agent host
oo skills validate <path>	Validate a skill directory
oo skills publish <skill>	Convert one skill into an OOMOL package and publish it
oo skills share [skill]	Generate a share prompt or share link for a published skill
oo skills install [packageName]	Install bundled skills or published skills
oo skills update [skills...]	Update installed oo-managed published skills
oo skills uninstall [skill]	Remove bundled skills or one oo-managed published skill

Key details:

• oo skills find <text> is an alias for oo skills search <text>.
• oo skills add [packageName] is an alias for oo skills install [packageName].
• oo skills remove [skill] is an alias for oo skills uninstall [skill].
• Running oo skills install with no package installs bundled skills.
• Bundled skills such as oo, oo-find-skills, oo-create-skill, and oo-publish-skill are published to supported local hosts when those directories already exist.
• Supported hosts include Codex, Claude Code, Hermes, WorkBuddy, Trae, OpenClaw, and QoderWork. Run oo skills preflight --help for the current host list exposed by your installed CLI.
• Published skills are installed into the supported host’s local skills directory, such as ${CODEX_HOME:-~/.codex}/skills/<skill-id> for Codex.
• oo skills list --source bundled|registry|local filters the installed skill list by source. Bundled skills ship with oo, registry skills come from published skill packages, and local skills are authored on this machine.
• Bundled skills are synchronized automatically during startup when needed, so oo skills update only targets published oo-managed skills.
• Use oo skills init, oo skills validate, oo skills publish, and oo skills share when you are authoring a reusable skill instead of only installing one.

Files

Command	Purpose
oo file download <url> [outDir]	Download one http or https file and save it locally
oo file upload <filePath>	Upload one local file to the temporary file cache
oo file list	List previously uploaded files from the local sqlite store
oo file cleanup	Delete expired upload records from the local sqlite store

Key details:

• oo file download defaults to file.download.out_dir when configured, or ~/Downloads otherwise.
• Downloads resume when the server supports safe HTTP Range requests.
• Existing target files are never overwritten; oo appends _1, _2, and so on before the extension.
• Uploaded files expire after one day.
• Files larger than 512 MiB are rejected by oo file upload.
• A common agent workflow is: upload an input file, pass the uploaded file URL into a connector action or Cloud Task, wait for the task, then download the result file.

LLM

Command	Purpose
oo llm config	Print the current account’s LLM client configuration as JSON
oo llm json	Call the configured LLM, require JSON output, validate it against a schema, and retry malformed responses

Notable options for oo llm json:

• --schema <schema>: inline JSON Schema or @path to a JSON file
• --system <system>: system prompt text or @path to a text file
• --input <input>: input JSON or @path to a JSON file
• --max-retries <count>: maximum retry count
• --model <model>: override the configured model for this call

Logs

Command	Purpose
oo log path	Print the current debug log directory path
oo log print [index]	Print one previous persisted debug log file

oo log print 1 means the previous log file. oo skips the current run’s log file and reads earlier logs.

Telemetry

Command	Purpose
oo telemetry status	Show CLI telemetry status
oo telemetry enable	Enable privacy-constrained CLI telemetry
oo telemetry disable	Disable CLI telemetry

Shell Completion

Command	Purpose
oo completion <shell>	Generate a shell completion script

Supported shells:

• bash
• zsh
• fish

Related Docs

• oo-cli Guide
• oo-cli on GitHub