ChatCut CLI

The small command-line entry point for the official ChatCut Desktop app. It contains no video editor, second MCP server, downloaded skills catalog, or third-party runtime dependencies. Desktop owns editing, agent connections and the skills shipped with that app version.

The CLI tools and skills route requires @chatcut/cli 0.1.2 or later. Merging source changes alone does not publish a new npm version.

Any agent that can run commands on the user's computer can use Desktop through the CLI. The agent runs these commands; the user only handles sign-in or OS approval buttons when needed:

npx --yes @chatcut/cli connect --json
npx --yes @chatcut/cli skills list --json
npx --yes @chatcut/cli skills read product-help
npx --yes @chatcut/cli tools list --json
npx --yes @chatcut/cli tools describe get_active_project --json
npx --yes @chatcut/cli tools call get_active_project --json

Generic connect, tools and skills require this source change to be published before those commands are available from npm. connect verifies one real Desktop tool call and returns the available tool/skill names. These commands reuse an already-running Desktop's authenticated local IPC connection and its MCP tool dispatcher. They install/open the signed production Desktop only when needed, with the existing publisher checks. Tool calls do not launch a second Electron runtime. They do not require native host registration or a host restart. Skill content comes from the installed Desktop version, so discover names rather than assume a newer skill is present. skills read <name> --file references/<file> reads a supporting file within that skill. Tool schemas come from the live server.

For tool arguments, use --args-file <file> or --args-file - with JSON on stdin; --args '<json>' is also available. Omitted arguments mean {}. Check the exit code and ok, and preserve the returned MCP result and original errors. Calls are never automatically retried: a timeout can follow a state change. --timeout <seconds> sets a call timeout between 1 and 1800 seconds (default 300). The CLI exposes the same Desktop tools and their permissions; invoking editing tools can change a project. CLI access is separate from tools loaded into the host's own tool table and should be reported accordingly.

Cloud agents, including Grok Bot, must use their approved local-computer command capability to run this CLI. A cloud shell cannot reach the user's local socket; the CLI never exposes Desktop through a public tunnel or copies login secrets.

npx --yes @chatcut/cli app

# Optional permanent command:
npm install --global @chatcut/cli
chatcut
chatcut app

Node.js 22+ is required. Desktop supports macOS 13+ on Apple Silicon or Intel and Windows x64. This launcher does not install a GUI on Linux or a headless server.

chatcut and chatcut app reuse an installed, signed production app. When it is missing, they download the official artifact, validate its publisher, install it for the current user when necessary, and request launch. Repeated calls preserve the existing app, account and projects. Failed launch never triggers replacement. macOS copies use a new staging bundle and rollback rather than merging bundles. Windows uses the signed per-user NSIS installer. OS policy, missing privileges, and signature assessment failures retain their original evidence.

chatcut connect --json
chatcut connect --client codex --json
chatcut connect --client claude-code --json
chatcut doctor --json
chatcut doctor --client codex --json
chatcut doctor --fix --json
chatcut update --json

connect --client <name> is the optional native-host setup entry point. It opens/installs Desktop, asks Desktop to register or repair the supported agent integrations and sync its managed skills, then verifies the local MCP connection with a real tool call. Tools are provided over Desktop's MCP server. Use --client to select codex, claude-code, hermes, workbuddy, deepseek-harness, qwen-work, or doubao-work. Without --client, connect establishes CLI access without repairing native host registries; doctor --fix inspects and repairs all known integrations. Automatic connection and skill repair support Codex, Claude Code, Hermes, WorkBuddy, the DeepSeek Harness Desktop profile, and Qwen Work (千问办公). Missing host configuration homes are skipped; the command does not install these agents.

Doubao Work (豆包工作) supports automatic managed skill synchronization to ~/DoubaoWork/skills and live Desktop connection diagnosis. First-time MCP registration uses Doubao's signed-in custom connector UI. connect prepares an app-owned local setup skill and exact connector settings, then opens a Doubao task with the skill and request already selected. The user clicks Send and any required login or system permission buttons. Doubao's native computer-use tool fills and saves the official form, then verifies a real connector tool call; users do not enter commands, paths, transport types, or environment variables. The setup task uses /bin/sh with the launcher as a separate argument on macOS, because Doubao splits its command field on spaces. Windows setup uses cmd.exe with separate arguments and still needs native acceptance. System permissions may require a Doubao restart; the task must resume after that interruption. Once registered, doctor --fix refreshes the stable launcher and owned skills. A host is connected only after its authenticated live MCP session has successfully listed tools; closing that session clears the observation. A successful tool call is reported separately in discovery.lastToolCall. This is configured client attribution, not a new host identity/security boundary. A standalone doctor probe does not establish host discovery. The command reports incomplete setup as a failure while the host setup task is pending. Opening the task is not connection success. It never writes a guessed Doubao MCP registry or borrows browser credentials.

DeepSeek's configuration adapter uses $DSH_HOME/profiles/desktop/cordis.patch.yml (default ~/.dsh) and $DSH_HOME/skills. Qwen's legacy adapter uses ~/.qwenworkcn/mcp.json and ~/.qwenworkcn/skills; Qwen Work 1.4.0 uses an account-scoped connector registry and did not load this legacy registration in native testing. A written configuration is not a working native integration. Use CLI access while native registration is unresolved.

The command reuses doctor --fix, including its standing opt-outs and preservation of custom skills. Read the returned findings for skipped hosts or remaining actions; passing checks does not mean an opted-out or unavailable host was connected. Read hostHandoffs even when ok is true: the diagnostic client cannot establish acceptance in the calling Agent. Check the Agent's currently loaded skills and tools first, and avoid another reload if they already work. Otherwise follow its specific action:

| Host | Agent should tell the user | Acceptance evidence | | ----------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Codex CLI | Exit and reopen the agent session | Fresh CLI 0.160.1 read the installed skill and called Desktop successfully; necessity of each reload alternative not established | | Codex desktop app | Try a prepared new conversation; restart Codex if tools remain absent | App reload acceptance pending | | Claude Code | Exit and reopen the agent session | Native acceptance currently blocked by sign-in | | Hermes | Use CLI access immediately; use a fresh session for native configuration changes | Native Hermes 0.22.5 skill_view and Desktop MCP call passed; CLI route also called Desktop successfully | | WorkBuddy | Use CLI access; native registration still needs repair | Native 5.9.3 lacked tools after app restart and a new task; real Agent completed the CLI route | | DeepSeek Harness | Use CLI access; native registration still needs repair | Real Desktop Agent completed connect and product-help read through CLI; native tool-table registration remains unresolved | | Qwen Work | Use CLI access; native account-scoped registration still needs repair | Real 1.4.0 Agent read a skill and called Desktop through CLI; native tool-table registration remains unresolved | | Doubao Work | Continue in a new task; restart only when its system permission screen requires it | Native macOS 2.34.9 self-install and new-task tool call passed; optimized CLI handoff acceptance pending |

Prepare continuation context before asking the user for a restart or a new chat. The user should only click the host's buttons, without copying commands, editing config, or re-entering their request. After resuming, the Agent must read a managed skill and call a real Desktop tool. hostAcceptance explicitly keeps this separate from standalone diagnostic success. A fixture test or a configured registry alone does not qualify a host as natively accepted. JSON results identify this entry point with command: "connect".

Doctor without --fix does not install or open Desktop or change agent settings. It inspects a running Desktop through its authenticated user-scoped IPC, then starts a fresh local MCP client, negotiates the protocol, lists tools and calls get_active_project. An empty active project is valid. A cached list followed by a failed tool call is a failed check. Desktop may serve MCP reads while its GUI is closed; a working MCP probe does not establish that the GUI is running or that the current host conversation has loaded its tools and skills.

--fix explicitly opens/installs Desktop, asks Desktop to repair the selected supported integration(s), and checks the result. Desktop continues to own host configuration and skill synchronization, including its standing opt-outs. Unchanged manifest-owned obsolete skills can be removed. User-edited, foreign, symlinked and ambiguous overlapping skills are preserved and reported. Different client variants are intentional and must not be deduplicated by name alone.

Doctor reports original errors and remaining actions. Sign in within Desktop when needed; start a new agent conversation after its connection or skill set changes. A fresh diagnostic client cannot prove the current host's discovery state. Older Desktop releases without the doctor IPC report an update requirement.

When a host CLI fails, Desktop reports its source error code and operation stage and marks omitted command output explicitly. Inspect that host locally for the remaining error text; an omitted message is an evidence gap, not a diagnosis.

Commands that may open Desktop (app, connect, tools, skills) accept --source <channel> (or CHATCUT_INSTALL_SOURCE) to record which distribution channel the installation came from, for example --source oss_viral_cloner. The CLI leaves the value in Desktop's install-handoff.json. Desktop adopts it when it starts, or on the first call that needs it if it is already running, keeps the first channel for that profile, and sends it with its analytics and forwarded agent calls. It is an analytics label, not a credential, and failing to record it never blocks setup. Values are 2–48 letters, digits or underscores starting with a letter. --source requires 0.1.3 or later; older versions ignore the environment variable. See docs/development/analytics/install-source.md for the channel registry.

update is explicit and separate from diagnosis. Close Desktop first; it never forces a running editor to quit. It uses the official signed release, preserves user data and refuses downgrades. Shared Windows installations use their existing app updater or an interactive official installer.

--json writes one JSON result to stdout; progress goes to stderr. Exit 0 means the requested operation completed or all required diagnostic checks passed. Exit 1 retains the failing stage, original cause and remaining action. Informative opt-outs, unavailable optional hosts and preserved custom skills are not failures.

The historical @chatcut/skill package also exports a chatcut executable for its cloud job workflow. Use npx --yes @chatcut/cli ... without changing that install, or explicitly remove the old global package before installing this one globally. Do not use --force to overwrite another package's executable. Its saved cloud credentials and jobs are not migrated or deleted by this CLI.

For contributors: run npm test and npm pack --dry-run from this directory. Native install/trust boundaries have deterministic fixtures on macOS, Windows and Linux CI; actual publisher validation and a real installation remain separate release acceptance evidence. Bump apps/cli/package.json to release changes. The full production workflow (.github/workflows/sst-production.yml) checks the npm version, tests the CLI, packs it and publishes with npm Trusted Publishing. Editor-only runs skip publication. The @chatcut/cli npm package must trust ChatCut-Inc/chatcut, workflow sst-production.yml, environment production. Inspect the tarball and verify the published npx entry point on a clean supported machine before advertising availability.