chatium v3

Source Git CLI, replacing the earlier chatium npm implementation without backward compatibility. Requires Node.js 22+ and Git on macOS, desktop Linux, or Windows, plus a browser and available system secret storage. Version 3 completely replaces the previous package; old commands and settings are not migrated.

Install and start

After the public v3 release:

npm install -g chatium@latest
chatium --version
chatium clone your-account.example.com

Use your account domain, HTTPS origin, or the exact repository URL from its Source Git page. Confirm chatium --version reports a 3.x version. Browser login requires a real Auth2 account owner/developer. Clone then generates tsconfig, installs Git hooks, downloads IDE declarations and installs Chatium skills for Codex and Claude Code. You can open the resulting folder in your editor and start working. The initial Chatium skill is a template; full guidance is still pending.

In an existing checkout, run chatium setup after installing v3. If setup fails, fix the reported cause and rerun it in the preserved checkout. See the command and system requirements below.

Switch an existing repository to Chatium CLI

npm install -g chatium@latest
cd your-existing-repository
chatium setup

Setup signs in with the chatium-cli OAuth client, configures the repository's account-scoped Git credential helper, then generates tsconfig and installs hooks, typings and skills. Retry the original Git command afterwards; you do not need to clone again. Global helpers and other accounts are preserved. An existing CLI session issued to the old client requires one browser login. Cancellation or failure preserves that session for another transition attempt; old refresh tokens are never reused under the new client.

Source Git rejects old-client tokens for reading and pushing. The old OAuth client can no longer authorize or refresh, but logout can still revoke its saved session. The old OAuth shell installer has been removed. Transition messages support Russian and English. CLI language comes from LANGUAGE, LC_ALL, LC_MESSAGES, then LANG, with English fallback. HTTP messages use Accept-Language; browser pages use the user's existing language settings. Existing unrelated CLI messages are unchanged.

Build and check locally

npm ci --registry=https://registry.npmjs.org
npm run check
npm run smoke:native
npm pack
node dist/src/cli.js login https://your-account.example.com

Source and tests use TypeScript 7.0.2 (the stable npm latest when implemented), pinned exactly. build compiles both to ESM; typecheck uses strict checks without emitting files. Run the build/check before npm pack: the package includes only dist/src, package metadata, README and MIT license. The installed executable is chatium; it runs compiled JavaScript and does not need TypeScript at runtime. All checks and publication are manually invoked. This package is outside the private Lerna release flow. No scripts publish to npm and no GitHub Actions workflow is provided.

Updates through npm

Automatic updates are enabled by default. After a successful login, clone, setup, get-typings, get-skills, or merge/rebase setup, a detached worker checks public npm at most once an hour. The command finishes without waiting. The worker installs only npm latest, provided it is a non-deprecated stable release in the current major that supports the running Node version; it never downgrades or selects another version. When latest moves to the next major, this major stops receiving automatic updates. Checkout, commit, credential helper, logout, offline commands, help, failures and cancellation do not trigger updates. Nested CLI calls do not launch additional workers.

chatium update --check
chatium update

Both commands perform a fresh check outside or inside a checkout. --check only reports the current and available versions, Node, installation prefix, automatic-update setting and previous attempt. update installs with visible progress. No available update is successful; an unsupported installation, failed check or busy updater returns an error. Set CHATIUM_NO_AUTO_UPDATE=1 to disable automatic updates; manual commands still work. Background results never appear during ordinary commands.

Only real global npm installations are updated, including custom prefixes and nvm. Source checkouts, npm link, local dependencies and npx caches are excluded. The updater invokes npm through the running Node and targets this installation's prefix, not npm's current default. It runs outside the checkout and preserves absolute hook/helper paths. It does not ask for elevated privileges.

Active CLI commands, including nested Git helpers, defer installation. A deferred candidate can be installed after the next eligible command, but metadata from a previous run is fetched again before installation, even within the hourly interval. A registry failure prevents installation; fresh metadata from the current run is reused without a second request. Coordination and diagnostic state are stored per installation under $XDG_STATE_HOME/chatium/updates (otherwise Windows %LOCALAPPDATA%, or ~/.local/state). Do not remove these files while commands or npm are active.

Recovery and major upgrades

npm replacement is not atomic. A new concurrent invocation can hit missing files during installation and need a retry; external npm commands do not participate in CLI locking. Failed npm installation can leave Chatium unusable, including chatium update --check. There is no automatic backup or rollback. Reinstall directly with npm, using the same prefix:

npm install --global --prefix "/your/original/prefix" [email protected] --registry=https://registry.npmjs.org

Replace the example version with the version you want. To keep that version, set CHATIUM_NO_AUTO_UPDATE=1. The updater also records a recovery command and its last error in state.json. To move to the next major, run npm install -g chatium@latest, adding --prefix for your custom prefix.

Clone

chatium clone test.chatium.ru
chatium clone https://yowad.ru
chatium clone https://your-account.example.com/s/source-git/your-account.git
chatium clone https://your-account.example.com/s/source-git/your-account.git "my checkout"

Clone opens browser login when needed or reuses the same session as login. Without a destination, the origin's hostname (without scheme or port) is used, including for full repository URLs. For example, chatium clone yowad.ru creates yowad.ru, even if the account name is yowadtravel. The new checkout's account-scoped credential helper and useHttpPath are configured before its initial fetch; subsequent ordinary Git commands use the same session. Global credential helpers remain unchanged.

The command reports success after cloning and running setup: local TypeScript configuration, managed hooks and declarations, then Chatium skills for Codex and Claude Code. The generated root tsconfig is overwritten even if tracked; other tracked files and legacy helper scripts are preserved. Project installation/lifecycle scripts are not run. The credential helper refers to this installed CLI and Node executable, so keep them available while using the checkout.

If preparation fails, the checkout is retained and the error names its location and recovery commands. Run chatium setup inside it after fixing the cause. Git clone failures retain Git's exit code and normal cleanup behavior; the CLI never removes an existing destination to retry.

Custom domains remain in the remote URL, OAuth and setup, with a separate session per origin. Account-domain clone requires backend support; external proxies and path prefixes are unsupported. See the Source Git guide.

Login

chatium login https://your-account.example.com
chatium login your-account.example.com
chatium login

Inside a Source Git checkout, the URL defaults to the origin remote, including from subdirectories. Outside a checkout, supply an account URL. Authorization requires a real Auth2 account Owner or Developer and grants repo:read repo:write code:execute. Login reuses a valid local session with all three scopes, refreshes an expired one, or opens the browser as needed. Press Ctrl+C to cancel; unattended login times out after five minutes.

Account URLs require HTTPS. HTTP is accepted only for literal loopback hosts 127.0.0.1 and [::1], for local development. The local OAuth callback continues to use HTTP. Credentials embedded in URLs, query strings, and fragments are rejected.

In Chatium Code, login checks the existing native session first. Otherwise it exchanges the injected CHATIUM_TOKEN only when the target origin exactly matches https://${CHATIUM_ACCOUNT}, saves the ordinary OAuth pair, and skips the browser. Invalid local values or server 401/403 fall back to browser login; transport, server and malformed-response failures stop the command.

Logout

chatium logout your-account.example.com
chatium logout

A hostname without a scheme defaults to HTTPS and uses the same session as the full HTTPS origin. Without an argument, logout uses the checkout's origin, including from subdirectories. It revokes the saved refresh-token family on the server before deleting the local native entry. All local clones of that origin share the session; other origins and other devices' token families are unaffected. No saved entry is a successful no-op. Logout never opens the browser or clears the browser's Chatium session.

A network error or unconfirmed response retains the entry and exits unsuccessfully: retry logout when connected. If server revocation succeeds but native deletion fails, the error explicitly says so; unlock the native store and retry. Server revocation accepts consumed refresh tokens and repeated requests. The next Git credential request can start a new browser login. Logout is disabled while both managed Chatium Code variables are present.

Execute code

chatium exec 'return await someFunction()'
printf '%s\n' 'return { ok: true }' | chatium exec

Run chatium exec inside a Source Git checkout. It executes the snippet against the successful Source Build for the checkout's exact committed HEAD; if the checkout has staged, unstaged, untracked or dirty-submodule changes, the command warns that they are unavailable but continues. Ignored files do not trigger the warning, and the snippet is never added to Git. The command may change account data. It has no read-only mode, rollback, or dedicated VM: execution reuses the account VM when available. Only account owners and developers can grant the separate code:execute permission.

The result goes to stdout: strings are printed without JSON quotes, other JSON values are serialized. console.* output and errors go to stderr. Pass one snippet argument or pipe a snippet to stdin.

Prepare hooks and typings

chatium setup
chatium generate-tsconfig
chatium install-hooks
chatium get-typings
chatium get-skills
chatium typecheck
chatium generate-typings

Generated and migrated repositories provide npm run setup (chatium setup) for full repository preparation; the old install-hooks npm script is removed. chatium install-hooks remains available separately.

The old command names typings, sync-typings and tsconfig are no longer accepted.

Run these in a Source Git checkout, its subdirectory or a Git worktree. setup authorizes and configures the account-scoped Git helper, then generates tsconfig, installs hooks, downloads declarations, then installs the current Chatium skills. Both clone and setup print the checkout path and each preparation step, then report success once. Failures show the cause; clone preserves the checkout and suggests retrying setup. generate-tsconfig works offline and derives aliases from local folders and the account in origin; it overwrites even customized/tracked root configuration without staging. install-hooks also works offline. Only downloading declarations needs the shared OAuth session. typecheck regenerates tsconfig before running its pinned TypeScript/vue-tsc pair; generate-typings replaces .typings using the public files in package.json. These two explicit commands use npm; the generator follows its latest release without a Chatium CLI update. Setup does not run them. get-typings leaves hooks unchanged and scans .ts, .tsx, .js, .jsx and .vue files for scoped imports, excluding .git, .chatium, .typings and node_modules. It downloads builtin and external-account declarations; it does not generate the project's public typings.

Installation uses Git's common hooks directory. Only recognized Chatium-managed hooks can be replaced; all hook destinations are checked before writing. The hook invokes this CLI through absolute Node/CLI paths; after moving the installation rerun install-hooks. A foreign hook, symlink, or custom core.hooksPath (including an explicitly empty value) causes an error during install-hooks/setup; get-typings does not inspect hooks or core.hooksPath. The hook runs the installed CLI offline with Node and Git; no network access is needed during commit. Directory metadata must be a regular index file. ID insertion rejects symlink paths and atomically replaces the worktree file while preserving its permissions, formatting and partially staged edits.

Installed hooks run full setup after merge (including fast-forward pull) and after rebase. After branch checkout/switch, detached HEAD checkout or worktree creation, only tsconfig is regenerated, without network access. Checkout of individual files, amend, push and pull without changes do not trigger preparation. Automatic setup downloads skills too and may open the OAuth browser. Failures print the cause and a manual retry command without failing the completed Git operation; manual setup/generate-tsconfig still fail normally. Existing checkouts receive these hooks after chatium setup or chatium install-hooks.

Typings output is restricted to declaration files inside this checkout's node_modules. The complete response is checked before writing declarations: traversal, tracked files, symlinks, and conflicting paths are refused. Valid untracked declarations are replaced regardless of their creator; stale files are retained. Each file is replaced through a temporary file so a failed write does not truncate the existing declaration. A failure midway can leave earlier files updated; rerun the command after fixing the cause.

The CLI adds /node_modules/ to Git's local info/exclude. Only tsconfig generation changes tracked configuration in older checkouts; legacy helper files are preserved but their installation workflow is no longer supported. The old /s/source-git/hooks/pre-commit endpoint has been removed. Run chatium setup in existing checkouts to install the CLI hooks instead of running .chatium/install-hooks.mjs. The installed merge/rebase hooks also run preparation after successful Git operations.

Native storage and recovery

One native secret per account origin stores the access/refresh pair, expiry and scope. Clones of one account share its session; different origins have independent entries. Storage errors fail the command: unlock or repair the system store and retry. No plaintext fallback exists. macOS uses Keychain and open; Windows uses Credential Manager and the default browser. Linux needs xdg-open and a working desktop Secret Service for persistence across reboots; the native dependency's kernel-keyring fallback may require a new login after reboot.

A refresh-pending marker is saved in the same secret before the HTTP request. If the response is lost, the process dies or saving the rotated pair fails, retrying performs a new browser login instead of reusing the old refresh token. proper-lockfile coordinates processes per origin in the user's local state directory, using a heartbeat and a 10-second stale threshold. Lock files contain no tokens. Do not remove active locks. A killed process's lock may take about ten seconds to recover. Coordination is local to a desktop, not shared across machines.

Git helper contract

chatium credential-helper <account-origin> get|store|erase uses Git's stdin/stdout protocol. The explicit origin binds it to the account; unsupported hosts, protocols, usernames and repository paths receive no tokens. store cannot overwrite the OAuth pair. erase removes only a matching current access token; it does not revoke server tokens.

Setup tooling must configure the helper locally for the exact account context, reset inherited helpers for that context and enable credential.useHttpPath there. Do not configure it as an unrestricted global helper. Clone configures this automatically.

Test boundaries

Tests build, pack and install the artifact in temporary global prefixes. TypeScript test-only Node loaders substitute the external native keyring and browser launcher, using shared storage across child processes. These fixtures are excluded from the npm artifact. Updater tests also substitute registry metadata and map exact test versions to local tarballs; npm performs real global replacement in isolated prefixes. They exercise busy/deferred updates, killed workers and process-tree termination. Run the updater suite on each supported OS (node --test dist/test/update.test.js after build); macOS checks alone do not verify Linux or Windows installation and termination behavior. Real backend coverage lives in backend/src/__tests__/api/source-git-npm-cli.api.test.ts and exercises OAuth and actual Git fetch/push.

smoke:native creates and deletes a unique temporary native keyring entry and opens a local page in the actual browser. Run it on each supported desktop OS before release. Native smoke is separate from the backend OAuth flow; deterministic substitutions alone do not demonstrate native platform integration.

Run the affected backend regression suite from the monorepository after installing the CLI's development dependencies:

cd backend
npm run typecheck -- --pretty false
npm run test:with-instance -- \
  src/__tests__/api/source-git-npm-cli.api.test.ts \
  src/__tests__/api/source-git-oauth-revoke.api.test.ts \
  src/__tests__/api/source-git-tooling-migration.api.test.ts \
  src/modules/sourceGit/__tests__/sourceGitPackage.test.ts \
  src/modules/sourceGit/__tests__/sourceGitTypingsSync.test.ts \
  src/modules/sourceGit/__tests__/sourceGitRoutes.test.ts --runInBand

The test-instance lifecycle builds the backend and cleans up its services afterwards. The installed-CLI suite covers actual OAuth/Git, clone preparation and recovery; the revoke suite forces both refresh/revoke orders and checks independence of token families. Other suites cover hook behavior and typings contracts.

Chatium skills

Run chatium get-skills (or npm run get-skills in newly generated/migrated projects) to download the current default branch of https://github.com/chatium/chatium-agent-skills. Git and network access are required; Chatium login is not. The command works from subdirectories and worktrees.

Whole skill directories are copied independently into .agents/skills/ and .claude/skills/ for Codex and Claude Code. Names starting with chatium are managed: local edits are replaced and retired skills removed. Other skills and agent files remain yours. No agent configuration or lock file is generated. The source currently contains a development template; substantive guidance will be maintained there.

The complete source and destination paths are validated before replacement. Download/validation failures preserve installed skills. Fix the reported cause and rerun chatium get-skills; retry also repairs a partial filesystem failure. Ctrl+C cancels download and removes temporary files.

Only /.agents/skills/chatium* and /.claude/skills/chatium* are excluded via local Git info/exclude. New repository templates and source-git migrate-tooling include these rules in .gitignore, preserving other rules. The command does not edit tracked .gitignore or stage/untrack files.

Upload local files

From the account's Source Git checkout (including subdirectories):

chatium storage upload ./photo.jpg ./document.pdf
chatium storage upload --protected ./private.pdf
chatium storage upload -- -filename.txt

The account comes from the origin remote; the CLI reuses its OAuth session or opens login. Files are public by default. Paths are relative to the current directory; directories are not uploaded. Each successful upload prints a text block with file, file_hash, download_url, get_url, and thumbnail_url (800px wide, when the format supports thumbnails). Protected URLs are unsigned; use @app/storage helpers in your application to obtain authorized access URLs.

Files upload sequentially. File errors go to stderr and remaining files continue; any failure gives exit code 1. Authorization failure or cancellation stops the command. Successful uploads remain stored. The backend must support /s/source-git/storage/upload-url before this CLI command is released.