Standalone CLI

@yoooclaw/cli is the standalone yoooclaw / yc command line — it ships its own background daemon and doesn't require the openclaw client app to be online. Its design follows Lark's lark-cli: a service-oriented command tree, a three-tier command system (Shortcuts / Service Commands / Raw API), unified --format, and Agent-Native.

Current status: all commands available

Every service command has landed: local read-only commands (🟢, pure disk reads) work out of the box; daemon commands (🔵) and control commands that require the daemon to be running (🟡) collaborate over a local HTTP RPC. Phones can reach the local daemon via yoooclaw's hosted Relay; when Relay is unavailable, you can still fall back to cloudflared / tailscale serve to reverse-proxy the local HTTP server.

Installation

There are two distribution channels with identical functionality — pick based on whether it's convenient for you to have Node installed. The npm package is an extremely thin Node launcher that pulls the current platform's native Go binary via optionalDependencies at install time; the native binary channel downloads the same Go binary directly.

Platform support

The npm channel supports x64+arm64 on darwin/linux plus win32-x64 (the launcher needs Node ≥ 18). Native direct install supports x64+arm64 on darwin/linux (install.sh) and Windows x64 (install.ps1; Windows on ARM runs it through the OS x64 compatibility layer). Windows has two differences: credentials are stored in plaintext at ~/.yoooclaw/credentials.json (no OS keychain hardening — yoooclaw doctor flags this as skip with a hint), and yoooclaw daemon stop exits gracefully via HTTP /daemon/stop instead of a POSIX signal. See Storage & Directories for details.

A. npm (thin Node launcher + platform Go binary)

No install (npx, always pulls the latest version):

npx @yoooclaw/cli --help          # main command
npx @yoooclaw/cli notification +today

Global install (provides both the yoooclaw and yc commands):

npm i -g @yoooclaw/cli
yoooclaw --help        # main command
yc --help              # equivalent short alias

npx @yoooclaw/cli always invokes the yoooclaw entry point (yoooclaw and yc point to the same executable).

B. Native binary (no Node required)

A single-file Go executable, with faster cold starts and lower resource usage than the old TS/Bun form.

macOS / Linux:

# auto-detect platform, download, verify sha256, write to ~/.local/bin (served from Alibaba Cloud OSS)
curl -fsSL https://artifact.yoooclaw.com/cli/install.sh | sh

# specify version / install dir / force overwrite (the only way to install a prerelease)
curl -fsSL https://artifact.yoooclaw.com/cli/install.sh \
  | sh -s -- --version 0.12.0 --dir ~/bin --force

# also write the install directory into your shell config (PATH)
curl -fsSL https://artifact.yoooclaw.com/cli/install.sh | sh -s -- --modify-path

The install directory defaults to ~/.local/bin, falling back to /usr/local/bin if that is writable. The installer no longer touches any shell config file by default — it only installs the binary. To have a new terminal run yoooclaw directly, pass --modify-path explicitly; only then does it idempotently add the install directory to your login shell's config (zsh → .zshrc, bash → .bashrc / .bash_profile, fish → config.fish, POSIX shell → .profile), telling you to reopen the terminal or source the file when it changes anything. Without --modify-path you'll need to add the install directory to PATH yourself; --no-modify-path is still accepted for backward compatibility and is equivalent to the default (no change).

If OSS is not reachable for you, the GitHub-hosted script works the same way (downloads from GitHub Releases, same flags):

curl -fsSL https://raw.githubusercontent.com/YoooClaw/cli/master/scripts/install.sh | sh

The installer no longer has --beta

Without --version the installer only resolves stable releases; --beta has been removed and now fails with a hint to use --version <prerelease> instead. Prereleases also no longer overwrite the live install script or the latest marker, so the default install is always a stable release.

The installer first verifies the binary runs via its full path, then checks whether the PATH it inherited finds it by name, and prints a PATH-independent full-path invocation. On Linux, if an Agent reports yoooclaw: command not found while a regular terminal works: the Agent's / service's non-interactive bash -c usually doesn't read .profile / .bashrc, so neither --modify-path nor reopening a terminal is guaranteed to help — add the install directory to PATH in the Agent runner's / service's startup environment and restart that process, or just use the full path the installer printed (e.g. /home/admin/.local/bin/yoooclaw).

Windows (PowerShell 5.1+, no Node/npm, no admin rights):

irm https://artifact.yoooclaw.com/cli/install.ps1 | iex

# specific version / overwrite to upgrade
& ([scriptblock]::Create((irm https://artifact.yoooclaw.com/cli/install.ps1))) -Version 0.12.0 -Force

It installs to %LOCALAPPDATA%\YoooClaw\bin (yoooclaw.exe / yc.exe) and adds it to the current user's PATH automatically (-NoModifyPath disables that). If it detects an older version installed via npm i -g @yoooclaw/cli, it confirms the new native CLI runs and then automatically runs npm uninstall -g @yoooclaw/cli (-KeepNpm keeps it); an npm cleanup failure never rolls back the verified new version. Other parameters: -InstallDir, -Activate, -HermesProfile (same meaning as install.sh's --dir / --activate / --hermes-profile).

Direct-install platforms: darwin-arm64 / darwin-x64 / linux-x64 / linux-arm64 / win32-x64.

You can also download the binary manually from GitHub Releases or the OSS artifact directory and verify it against the checksums.txt next to it.

yoooclaw update self automatically detects the current install source (npm vs native binary) and OS and gives you the matching upgrade command (the native commands already include --force / -Force) — don't mix the two channels. See Updating & Upgrading.

C. Unattended install on WUYING cloud desktops

For environments like Alibaba Cloud WUYING desktops that should be ready for an Agent right after install. One command installs the native CLI → writes the account api-key → initializes a default config non-interactively → installs Skills for the chosen Agent host → takes standalone CLI ownership and starts the daemon (preferring login autostart; falling back to a detached daemon when no user service manager is available).

export YOOOCLAW_API_KEY='ock-xxxx'
curl -fsSL https://artifact.yoooclaw.com/cli/install-wuying.sh \
  | sh -s -- --api-key "$YOOOCLAW_API_KEY" --skill claude --env production

# already installed, upgrade only: --api-key can be omitted (keeps existing credentials);
# --force overwrites the binary and installed Skills
curl -fsSL https://artifact.yoooclaw.com/cli/install-wuying.sh \
  | sh -s -- --skill codex --force

Option	Description
--skill <agent>	Required. Skill host, passed straight to yoooclaw skills install --agent; currently claude / codex.
--api-key <key>	Write a new account api-key; omit it to keep existing credentials (upgrades). The script never prints the key and writes it via stdin into the 0600 shared credentials file — reference an environment variable as in the example to keep it out of shell history.
--env <name>	development / test / production; defaults to PHONE_NOTIFICATIONS_ENV, then production. Persisted to the profile config for the systemd service.
--version / --dir / --profile / --force / --modify-path	Same as install.sh. The live script installs the stable CLI it was released with by default; --version is the only way to install a prerelease.

For Claude / Codex, the script also writes the CLI's absolute path and the chosen profile into the installed YoooClaw Skills so the Agent calls the full command regardless of whether ~/.local/bin is on PATH; reinstalling updates that block, and existing Agent sessions need to reload Skills or start a new session.

Uninstall

# stop the daemon + remove the binary and config, keep notification / recording / image data
yoooclaw uninstall

# wipe the data too (clears ~/.yoooclaw), no confirmation prompt
yoooclaw uninstall --data --yes

The native binary form removes its own yoooclaw and yc; a native Windows install also removes the user PATH entry and install directory written by install.ps1 (including cross-drive installs), reported as userPathRemoved / installDirsRemoved. The npm install form is managed by node_modules and can't remove itself — uninstall will prompt you to also run npm uninstall -g @yoooclaw/cli.

5-minute quickstart

# 1) Interactive wizard: enter your Relay api-key, generate config.json and a
#    gateway token, and automatically start the daemon in the background
#    (no need to run daemon start separately)
yoooclaw config init

# 2) Check status: PID, listening port, relay, number of light rules, latest ingest
yoooclaw daemon status

# 3) Look up today's notifications (once phone pushes have landed on disk)
yoooclaw notification +today

config init automatically brings up the daemon in the background at the end, and registers user-level login autostart (macOS launchd / Linux systemd user service / Windows Task Scheduler — no admin privileges needed). For a Linux server that should start at boot even with nobody logged in, also run yoooclaw daemon autostart enable --boot. If you enter an api-key in the wizard, it connects to Relay and just works out of the box; if you left it blank, set one afterward with yoooclaw auth set-api-key <ock_xxx> and then yoooclaw daemon restart so the daemon connects to Relay. To only register autostart without starting the daemon right now, add --no-start; to only start it once without leaving autostart registered, add --no-autostart. Check autostart state with yoooclaw daemon autostart status — see Command Reference · daemon.

For multi-phone / multi-account setups, give each key a stable label; the daemon opens one Relay tunnel per label, and inbound data carries the matching clientLabel:

yoooclaw auth add-api-key <ock_phone_a> --label phone-a --default
yoooclaw auth add-api-key <ock_phone_b> --label phone-b
yoooclaw daemon reload
yoooclaw tunnel status
yoooclaw notification +today --client phone-a

Server / headless deployments (wrapped in systemd / launchd):

yoooclaw daemon start --bind 0.0.0.0 --port 18365 --no-detach

Binding to 0.0.0.0 requires a gateway token to already be set, or startup is refused.

Recording sync and ASR

The daemon receives transcripts and summaries written by the app / cloud via recordings.result.write (optionally downloading the audio in the background if an ossUrl is included) into the current profile's recordings/. Audio downloads reuse the Alibaba Cloud OSS SDK's multipart download (resumes within a single download run with bounded retries; 5 GiB max per audio file); when the app also sends an ossTaskId, an expired signed URL (403) is automatically exchanged for a fresh one and the download continues. Re-transcribing locally is triggered via recordings.retranscribe according to config; in the standalone CLI, ASR config is written once locally to recordings/asr-config.json, and the daemon reads it automatically when a request doesn't include an asr field.

# api mode: if --api-key isn't passed, the daemon falls back to the account-level ock- key
yoooclaw recording setup-asr --mode api --language auto --non-interactive

The current Go beta only supports api / model-proxy ASR. The local and yoooclaw modes are still kept in the config schema for compatibility with older requests, but are rejected during validation.

While recordings sync, the daemon appends state changes to recordings/state/events.jsonl, which the CLI can query directly or follow continuously:

yoooclaw recording list
yoooclaw recording +latest
yoooclaw recording events --since 1h --limit 50
yoooclaw recording events --id <recording-id> --watch

Agent-Native

The CLI itself is the Agent's toolset — there's no need to stand up a separate MCP server:

• Every command supports --format ndjson, so an Agent can stream and consume results incrementally;
• Failures uniformly return { ok: false, error: { code, message, hint } }, with error codes prefixed YOOOCLAW_*; local CLI errors return a non-zero exit code, and for raw HTTP results you should check both ok and the HTTP status;
• yoooclaw api <METHOD> <PATH> is a raw escape hatch straight to the daemon's HTTP API.

8 Skills ship with the package (unified local-data query, recording processing, device display & lights, cloud todos, distilling notifications into memory, data transfer, image / video generation, and tunnel debugging) to teach an Agent to call the commands directly. Before installing, you can check which Agent targets are supported:

yoooclaw skills targets      # see which Agents this can be installed into
yoooclaw skills install      # auto-detect the single available Agent and install

See Agent Skill for details.

Next steps

• Command System & Output — the three-tier command system, global flags, output contract, and data directory.
• Command Reference — every subcommand listed by service, with examples.
• Agent Skill — install the bundled Skills into an Agent so it can drive the CLI on its own.