Skip to content

CLI Tree

ChatUp uses first-class top-level commands without forcing unlike browser artifacts and toolchains into one browser abstraction. Chrome for Testing, ChromeDriver, and Playwright own independent command sets, Python APIs, metadata, and storage roots.

Top-Level Commands

chatup
├── --help              # Show help for the current command
├── --version           # Print the package version
├── --tree              # Print the registered CLI tree with signatures
├── --tree-brief        # Print the same CLI tree without signatures
├── doctor              # Verify that ChatUp is callable
├── zsh                 # Configure zsh, plugins, and aliases
├── cc-connect          # Install ChatArch CC Connect
├── gitea               # Install ChatTea-compatible Gitea
├── glance              # Install the verified local ChatArch Glance runtime (do not start)
├── discourse           # Prepare Discourse config and ChatEnv-managed admin credentials
├── zulip               # Prepare Zulip Compose and ChatEnv-managed admin credentials
├── mysql               # Install ChatData-compatible MySQL
├── twikoo              # Install multi-instance Twikoo comment services
├── nginx               # Prepare user-level NGINX
├── crs                 # Install local Claude Relay Service plus Redis
├── claude              # Install/configure Claude Code
├── docker              # Check Docker and permissions
├── frp                 # Install FRP Client/Server
├── nodejs              # Install default LTS Node.js (nvm on POSIX; ChatArch portable ZIP on Windows)
├── uv                  # Install uv and ~/.chatarch/venv
├── chatgpt             # Install the new ChatGPT desktop app (includes Codex)
├── codex               # Configure Codex CLI and config files (uses CODEX_HOME when set)
├── cursor-agent        # Install/configure Cursor Agent CLI
├── opencode            # Install/configure OpenCode
├── lark-cli            # Configure official lark-cli with ChatEnv
├── hermes              # Install Hermes Agent and optional WebUI
├── workspace           # Initialize a ChatArch workspace
├── chrome              # Install regular Google Chrome for the current OS
├── snipaste            # Install Snipaste on macOS or Windows
├── iterm               # Install iTerm2 (macOS only)
├── macos               # Select supported macOS apps, including Blender on Apple Silicon
├── remotion            # Initialize a locked local video project
├── chrome-for-testing  # Manage Google Chrome for Testing browsers
├── chromedriver        # Manage ChromeDriver WebDriver servers
└── playwright          # Manage Playwright packages and Chromium browsers

Run chatup --tree to read back the registered tree with parameter signatures and command purposes. chatup --tree-brief keeps the same nodes and descriptions while omitting signatures. See Command Reference for complete options.

Local Glance Runtime

chatup glance [--version latest|chatarch-vMAJOR.MINOR.PATCH] [--runtime-home PATH] [--dry-run] [-i|-I]

The bare command performs setup. It supports only Linux amd64 in the current published matrix, downloads the exact ChatArch/glance archive, SHA256SUMS and BUILDINFO.txt, verifies them, and reuses the ChatGlance portable APIs. The default root is glance under the effective ChatArch home. Existing configuration and data are preserved and no server is started. Use chatglance runtime update for an explicit installed-version change.

Python Runtime

chatup uv
├── --venv, --venv-path PATH           # Target venv; default ~/.chatarch/venv
├── --python, --python-version TEXT   # Python version; default 3.12
├── -f, --force                       # Explicitly recreate the environment
├── --activate / --no-activate        # Update existing Bash/Zsh rc; enabled by default
└── --log-level TEXT                  # Log level

Missing rc files are not created; Windows skips this step. --no-activate leaves startup configuration unchanged. See Quick Start.

macOS Apps

chatup macos [--app snipaste|iterm|chrome|blender]... [--dry-run] [--log-level LEVEL] [-i|-I]

macOS only, with Snipaste, iTerm2, Chrome and Blender checked by default on Apple Silicon; Intel retains the first three. Space toggles and Enter installs. Repeat --app to select a subset, use -I to skip prompts, or --dry-run to preview. See the macOS install contract.

Remotion Video Projects

chatup remotion [PROJECT_DIR] [--browser-executable PATH] [--dry-run] [--log-level LEVEL] [-i|-I]

Create a local video project with locked dependencies. Missing directories prompt in a terminal, and existing unrelated paths are protected. See the Remotion contract for runtime requirements and browser behavior.

Chrome, Snipaste, and iTerm2

chatup chrome [--dry-run] [--sudo] [-y|--yes] [--log-level LEVEL]
chatup snipaste [--dry-run] [-y|--yes] [--log-level LEVEL]
chatup iterm [--dry-run] [--log-level LEVEL]

Chrome installs the regular system browser; Snipaste supports macOS and Windows; iTerm2 is macOS-only. See the install contract.

ChatGPT Desktop App

chatup chatgpt
├── --dry-run   # Show the install plan without running it
└── -y, --yes   # Accept Windows Store source/package agreements

Installs the new ChatGPT desktop app including Codex, not the Codex CLI or ChatGPT Classic. macOS uses Homebrew; Windows uses the exact official Microsoft Store ID. See the desktop install contract for prerequisites, Linux preview guidance, native storage paths and Python APIs.

Twikoo

chatup twikoo
├── --version VERSION
├── --repo OWNER/REPO
├── --home PATH
├── --name INSTANCE
├── --port PORT
├── --bind-address ADDRESS
├── --install / --no-install
├── --init / --no-init
├── --service / --no-service
├── --start / --no-start
├── --smoke / --no-smoke
└── --force

chatup twikoo installs Twikoo from GitHub Release binaries and prepares the multi-instance layout under ~/.chatarch/twikoo/instances/<name>/. Each instance gets its own bin/twikoo and adjacent bin/.env -> ../env/twikoo.env, so instances do not accidentally share the runtime-adjacent .env that the release binary auto-loads. It binds to 127.0.0.1 by default; local/public domain entry remains the responsibility of NGINX/public-entry.

Cursor Agent

chatup cursor-agent
├── --auth-json PATH
├── --auth-env PATH
├── -e, --env FILE_OR_PROFILE
├── --env-profile NAME
├── --save-profile NAME
├── --cli-config PATH
├── --agent-state PATH
├── --api-key-env NAME
├── --credential-store native|file-wrapper
├── --install-only
├── --verify / --no-verify
└── -i / -I

cursor-agent manages Cursor Agent CLI installation and login-state copying, and registers the ChatEnv CursorAgent config type. It never prints tokens in argv or output; Cursor-owned files such as auth.json, cli-config.json, and agent-cli-state.json are written safely, while ChatEnv profile .env files are left to ChatEnv's own storage mechanism. -e/--env can quickly read either an env file or a ChatEnv profile. For migrated Linux file auth on macOS, use --credential-store file-wrapper to write a token-free wrapper.

Common migration form:

chatup cursor-agent --auth-json ./auth.json --cli-config ./cli-config.json --agent-state ./agent-cli-state.json --credential-store file-wrapper -I
chatup cursor-agent -e ./cursor.env --credential-store file-wrapper -I
chatup cursor-agent -e work --credential-store file-wrapper -I

Artifact Identity

Backend Actual artifact Role
chrome-for-testing Google Chrome for Testing Launchable browser with extension and CDP support
chromedriver ChromeDriver WebDriver protocol server; not a browser
playwright Playwright package + Playwright Chromium Pins package, revision, browser version, and executable path

Chrome for Testing is Google's official distribution name. The for-testing suffix identifies the artifact; it does not expose a ChatUp test operation. None of the three backends has a test subcommand. Health checks are named doctor.

chatup chromium is intentionally unregistered. ChatUp will add an independent Chromium backend only after selecting and verifying a real Chromium source, revision contract, platform layout, and acceptance path.

Chrome for Testing

chatup chrome-for-testing
├── install
│   ├── --version VERSION
│   ├── --channel stable|beta|dev|canary
│   ├── --platform PLATFORM
│   ├── --home PATH
│   ├── --sha256 HEX
│   ├── --force
│   ├── --doctor / --no-doctor
│   ├── --output text|json
│   └── -i / -I
├── list [--home PATH] [--output text|json]
├── show [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── path [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── doctor [VERSION] [--execute|--no-execute] [--output text|json] [-i|-I]
├── remove [VERSION] --yes [--output text|json] [-i|-I]
└── gc [--dry-run|--apply] [--yes] [--minimum-age-hours HOURS]

--version and --channel are mutually exclusive for installation. Stable is the default when neither is given. Resolve-style operations require an exact four-component version; channels and old chrome@... / cft@... references are rejected.

chatup chrome-for-testing install --channel stable -I
chatup chrome-for-testing install --version 145.0.7632.6 --output json -I
chatup chrome-for-testing path 145.0.7632.6 -I
chatup chrome-for-testing doctor 145.0.7632.6 --output json -I

ChromeDriver

chatup chromedriver
├── install
│   ├── --version VERSION
│   ├── --channel stable|beta|dev|canary
│   ├── --match-browser PATH
│   ├── --match-cft-version VERSION
│   ├── --platform PLATFORM
│   ├── --home PATH
│   ├── --sha256 HEX
│   ├── --force
│   ├── --doctor / --no-doctor
│   ├── --output text|json
│   └── -i / -I
├── list [--home PATH] [--output text|json]
├── show [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── path [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── doctor [VERSION] [--execute|--no-execute] [--output text|json] [-i|-I]
├── remove [VERSION] --yes [--output text|json] [-i|-I]
└── gc [--dry-run|--apply] [--yes] [--minimum-age-hours HOURS]

The four install selectors are mutually exclusive. --match-browser reads --version from the supplied browser binary, resolves Google's build manifest first, and falls back to the milestone manifest; the browser and driver patch components need not match. --match-cft-version uses an exact CFT version directly. ChromeDriver is not involved in ChatPost's current extension/CDP Zhihu path.

chatup chromedriver install --channel stable -I
chatup chromedriver install --match-cft-version 145.0.7632.6 -I
chatup chromedriver install --match-browser /path/to/browser --output json -I

Playwright

chatup playwright
├── install [VERSION]
│   ├── --browser chromium
│   ├── --home PATH
│   ├── --force
│   ├── --doctor / --no-doctor
│   ├── --output text|json
│   └── -i / -I
├── path [VERSION] [--browser chromium] [--output text|json] [-i|-I]
└── doctor [VERSION] [--execute|--no-execute] [--output text|json] [-i|-I]

The Playwright backend accepts an exact three-component package version. install uses an available Node.js/npm runtime to install that package and download its declared Chromium revision into the same ChatArch-owned installation. path returns the executable resolved by Playwright itself. This backend creates no profile, launches no browser, and installs no ChromeDriver.

chatup nodejs -I
chatup playwright install 1.61.1 --output json -I
chatup playwright path 1.61.1 -I
chatup playwright doctor 1.61.1 --output json -I

Independent Storage

~/.chatarch/
├── chrome-for-testing/
│   └── <version>/<platform>/
│       ├── installation.json
│       └── <Google archive tree>/
├── chromedriver/
│   └── <version>/<platform>/
│       ├── installation.json
│       └── <Google archive tree>/
└── playwright/
    └── <playwright-version>/<browser>/
        ├── installation.json
        ├── package/
        └── browsers/

Chrome for Testing and ChromeDriver enforce official Google HTTPS provenance, optional SHA-256 verification, bounded ZIP extraction, and atomic directory replacement. Playwright uses npm package integrity and Playwright's browser manifest/download flow with the same atomic installation boundary. None modifies system Chrome, creates profiles, stores cookies, or manages accounts/extensions.

remove requires explicit --yes. gc defaults to dry-run and only targets backend temporary/backup directories older than the minimum age; deletion requires --apply --yes.

ChatStyle Interaction

Recoverable missing inputs use ChatStyle CommandSchema:

  • -i forces missing-value prompts for the current subcommand;
  • -I disables prompts and fails fast when required values are absent;
  • CHATARCH_AUTO_PROMPT=0/false/no/off disables automatic prompting;
  • CLI and prompted values receive the same validation;
  • destructive remove/gc paths still require --yes and are never relaxed by a default prompt.

Python API

Consumers choose an exact backend module instead of a generic Browser base:

from chatup.chrome_for_testing import resolve as resolve_cft
from chatup.chromedriver import resolve as resolve_driver
from chatup.playwright import resolve as resolve_playwright

browser = resolve_cft("145.0.7632.6")
driver = resolve_driver("145.0.7632.6")
playwright_browser = resolve_playwright("1.61.1", browser="chromium")
print(browser.binary_path)
print(driver.binary_path)
print(playwright_browser.binary_path)

ChatPost can select either a chatup.chrome_for_testing or chatup.playwright descriptor according to the proven task. It still owns isolated user-data directories, runner processes, CDP/bridge endpoints, extensions, manual login, account mapping, and the publication ledger.