@scalequality/cli

Run the ScaleQuality AI Workspace coding engine on your own machine, in any folder: a git repository, a folder inside one, or a folder with several repositories and other files. The conversation stays in the browser; the files, the commands and the git working trees stay on your computer.

Connect this computer

npx @scalequality/cli login          # prints a code; confirm it in ScaleQuality
npx @scalequality/cli add ~/code/app # a folder the AI Workspace may use (or pick it in the browser)

login prints a code and an address (<ScaleQuality>/devices?code=XXXX-XXXX). Open it while signed in to ScaleQuality and confirm the code; the computer is then yours, in that organization. Only confirm a code you started yourself.

Right after that, login installs a background service that keeps the computer connected, also after a restart. There is nothing to keep open.

| Command | What it does | |---------|--------------| | scalequality login [--api URL] [--name NAME] | Connects this computer (device code, like signing in to a TV app) and installs the background service. | | scalequality add [PATH] | Adds a folder (default: the current one). Only folders inside your home folder, never the home folder itself. | | scalequality service status | Whether the service is installed and running, what it runs and where it logs. | | scalequality service logs [--lines N] | The last lines of its log (default 100). | | scalequality service install | Installs it again, or updates it to the version you run. | | scalequality service start | Starts it again (the same as install), for example after it stopped. | | scalequality service uninstall | Stops and removes it. The computer stays paired but is not connected until you install it again. | | scalequality logout [--api URL] | Stops and removes the service, disconnects this computer in ScaleQuality and deletes the local credential. |

Every command takes --api URL for another ScaleQuality address (for example https://staging.scalequality.io); each address has its own credential and its own service.

What runs in the background

login copies this package and its dependencies to ~/.scalequality/cli/<version>/ (hard links when the disk allows, so it takes no extra space) and registers a per-user service that runs node ~/.scalequality/cli/<version>/node_modules/@scalequality/cli/bin/scalequality.mjs up --service at logon. It never runs from the npx cache, and nothing needs administrator rights:

| System | Service | Log | |--------|---------|-----| | macOS | LaunchAgent ~/Library/LaunchAgents/io.scalequality.cli.plist (RunAtLoad, restarted if it stops unexpectedly), loaded with launchctl bootstrap gui/<uid> | ~/Library/Logs/ScaleQuality/scalequality.log | | Linux | systemd user unit ~/.config/systemd/user/scalequality.service (Restart=on-failure) | ~/.local/state/scalequality/logs/scalequality.log | | Windows | Task at logon ScaleQuality\CLI (or, where a task cannot be created, a launcher in your Startup folder), started hidden | %LOCALAPPDATA%\ScaleQuality\Logs\scalequality.log |

On Linux the user service runs while you are logged in; login tells you when loginctl enable-linger $USER is needed to keep it connected after you log out. For another address, the names carry its host (for example io.scalequality.cli.staging-scalequality-io-1a2b3c). The service gets the PATH you had when you ran login, so sessions find git, npm and your toolchains; run scalequality service install again after changing them.

Where a service cannot be installed (a device management profile blocks login items, a Linux machine without a systemd user session), login says why and keeps the computer connected in that terminal instead; keep it open.

How to disconnect

• scalequality logout: removes the service and the CLI copy, disconnects the computer and deletes the credential.
• Disconnect in the AI Workspace: the service notices at its next poll, deletes the credential, removes its own definition and stops.
• scalequality service uninstall: only stops and removes the service (the computer stays paired).

The credential is stored in ~/.scalequality/credentials.json, readable only by you (mode 0600), one entry per ScaleQuality address; ScaleQuality keeps only its hash. It opens only this computer's queue: each session gets its own one-time secret, and no repository token is ever sent to your computer.

What the AI Workspace can do while the computer is connected

• start a session in one of your folders (at most 3 at once);
• add a folder you pick there (it is checked here: it must exist, be inside your home folder and not be the home folder);
• show you your folders to pick one, only while the folder picker is open in the browser: the subfolders of one folder of your home at a time (no files, no hidden or system folders, links only while they stay inside the home) and suggestions (git repositories under ~/GIT, ~/code, ~/projects, ~/Developer and similar folders, 3 levels down, plus the folders of your Claude Code and Codex conversations). Only folder names, their paths and the origin remote of repositories are sent, without any user or password;
• list your Claude Code (~/.claude/projects) and Codex (~/.codex/sessions) conversations, and import the ones you choose. Secrets (cloud keys, provider tokens, private keys, JWTs, connection strings, password=-style values) are removed on this computer before anything is sent, and the list itself goes without them. Only text is imported; tool results are left out and each tool call becomes a one-line summary.

What the service counts to suggest an import

When the service starts, and then at most once every 6 hours while it runs, it counts the Claude Code and Codex conversations on this computer, so the AI Workspace can offer to import them. It reads the same files the import list reads (~/.claude/projects/*/*.jsonl, or CLAUDE_CONFIG_DIR; ~/.codex/sessions/**/rollout-*.jsonl, or CODEX_HOME), at most the 500 most recent, each only up to its first message, and writes one line to its log, such as:

Found 28 Claude Code and 11 Codex conversations on this computer. You can import them from the browser.

Only the two numbers and the time of the count leave the computer (importable: {claudeCode, codex, countedAt} in the computer's inventory). No title, message, file name or folder name is sent until you open the import list in the browser and choose what to import.

A Claude Code conversation continued on the same computer and folder resumes from its own transcript: a copy without secrets is written into the engine's folder (~/.scalequality/workspace); the original file is never changed.

One session with a code (older screens)

scalequality connect <code> still works for a one-time code from an older AI Workspace screen: it runs one session in the current folder (--dir PATH, --api URL, --verbose) and ends when you press Ctrl+C twice. It is not listed in the help: login replaces it.

Requires Node.js 18 or newer and git. Any folder works; the CLI never runs git init, clones or fetches for you.

Any folder

• A git repository: its change is compared with HEAD.
• A folder inside a repository: the engine works in that folder; the repository tracks its change (only that folder's files).
• A folder that is not a repository (for example ~/GIT with many repositories inside): the repositories in it are found (up to 4 levels down, skipping node_modules, build output and hidden folders) and each one keeps its own change against its own HEAD. Files outside every repository are copied before the engine first changes them, into ~/.scalequality/workspace/sessions/ (never into your folder), so you can review, discard or rewind those changes too. Copies of sessions unused for 30 days are removed. Changes made by shell commands to files outside a repository are not tracked.

What runs where

On your machine:

• the coding engine (Claude Agent SDK), reading and editing files only inside the folder;
• the commands it wants to run, each one after you approve it in the browser (or after an "always allow" rule you created covers it);
• the diff of each repository against its HEAD at connect time (and of the other files against their copies), which is what the browser shows and what a pull request carries.

In ScaleQuality:

• the session, the conversation and every approval card;
• the model, through the ScaleQuality AI gateway of your organization;
• ScaleQuality tools (measurements, findings, agents);
• pull requests: the changed files are sent to ScaleQuality, which opens the pull request with your organization's repository connection after you approve it in the browser. Your machine never needs a provider token and never pushes.

Measuring uncommitted local changes (measure_change) runs only in the cloud workspace, where the scanners are; open a pull request to have the change measured.

The engine never pushes, never changes git remotes or credentials, and cannot read credential stores such as ~/.ssh, ~/.aws, ~/.netrc, your home .npmrc or the system keychain. Your shell environment is not passed through: only a fixed list of variables (PATH, HOME, locale, toolchain locations, proxies and CA settings) reaches the engine and its commands.

Approving commands

Before any command runs on your computer, the AI Workspace shows an approval card in the browser with the command, the folder, why it asks and a suggested rule:

• Run once runs it this time.
• Always allow stores a rule for this computer and folder, either the exact command or a prefix such as npm test*, and runs it. A prefix never covers anything chained, piped, substituted or redirected after it (npm test && … is asked again), and never a shell, sudo, npx or inline code.
• Deny tells the model it did not run.

Publishing (git push, remotes, gh, npm publish, image pushes), remote shells and copies, cloud and infrastructure CLIs and credential reads are never remembered: each run is asked again, and what the workspace policy denies is never offered at all. Rules are listed and deleted in the AI Workspace; a deleted rule stops applying in running sessions right away.

A card nobody answers in 10 minutes is withdrawn and the command does not run; stopping the request in the browser withdraws it too. File edits are not asked: they show in the browser as they happen, and each file can be discarded there.

Troubleshooting

• scalequality service status and scalequality service logs.
• scalequality up --verbose runs the same loop in the terminal, with diagnostic lines. It does not start while the service runs; stop the service first (scalequality service uninstall, then scalequality service install afterwards).
• Ctrl+C in up, or stopping the service, saves every running session first. Your folder keeps every change; closing the session in the browser also ends it on the computer.

For maintainers

dist/connect.cjs (every command) is built in the ScaleQuality ai-governance service from src/main/workspace-connect.ts:

# in scalequality-ai-governance-service
npm run build:cli            # -> dist-cli/connect.cjs
# here (scalequality-cli/connect)
npm run sync                 # copies it into dist/, or: npm run sync -- --from <dist-cli folder>
npm test

sync refuses a bundle built for a different @anthropic-ai/claude-agent-sdk version than the one in package.json.