@closedloop-ai/cli 0.3.0 → 0.3.1

package/README.md

@@ -25,14 +25,15 @@ The npm package is `@closedloop-ai/cli`; users of the earlier `cl` CLI can updat
 ## Commands
 
 - `closedloop login` (also `closedloop signup`): sign in, or create an account on the Free plan, with a code sent to your email.
-  - In a terminal, `closedloop login` asks for the email and the code.
-  - For an agent, two runs: `closedloop login --email you@example.com` sends the code; `closedloop login --email you@example.com --code BCDFG-HJKLM` finishes. Add `--totp <code>` (or `--backup-code <code>`) when the account uses two-factor authentication.
-  - `closedloop login --sso`: sign in through your browser instead, for workspaces that sign in with SSO (Entra, Okta). It prints a link and a short code; open the link, sign in to the app, type the code and approve. In a terminal it also copies the code to your clipboard and opens the link when you press Enter, then waits; an agent runs it again after you approve.
+  - In a terminal, `closedloop login` asks for the email and the code. Before creating a new account it asks for the data region: United States (US, the default) or European Union (EU). Existing accounts keep their region and are not asked to choose another one.
+  - `--region us|eu` explicitly selects where a new account's data should live. For an agent creating an account, two runs: `closedloop signup --email you@example.com --region eu` sends the code; `closedloop login --email you@example.com --region eu --code BCDFG-HJKLM` finishes. Use `us` for the United States. Without a region, an agent creating a new account is refused with `region_required` before an email code is requested; existing accounts can still sign in without the flag. Add `--totp <code>` (or `--backup-code <code>`) when the account uses two-factor authentication.
+  - `closedloop login --sso`: sign in through your browser instead, for workspaces that sign in with SSO (Entra, Okta). Add `--region eu` or `--region us` to choose the initial sign-in region. It prints a link and a short code; open the link, sign in to the app, type the code and approve. An existing account automatically completes sign-in in its home region, even when the command started elsewhere. In a terminal it also copies the code to your clipboard and opens the link when you press Enter, then waits; an agent runs the printed command again after you approve, keeping its `--region` flag.
   - An email whose account is in the other region (US or EU) signs in there, and the session stays with that region.
+  - `--region` never moves an existing account. A saved sign-in and `closedloop whoami` show the account's actual region. If a connection fails after browser approval in another region, repeat the same printed command: the CLI retains that pending sign-in and its original expiry. A rejected or expired request starts again with a fresh link and code.
   - A new account gets its own Free workspace unless the email was invited to one. One network can create three such accounts a day.
   - A new account is asked for its company website right after the code (in a terminal), or takes `--website <url>` (an agent passes it with `--code`). ClosedLoop AI researches the company from it before it analyses anything you send in; without it, imports run but nothing becomes insights. A website that cannot be saved does not undo the sign-in: the result names it and says to run `closedloop company --website <url>`.
   - Then its email domains: the domains of your colleagues' work addresses, which tell ClosedLoop AI who is a colleague and who is a customer. In a terminal it suggests them (from the website and your own address, never a personal one such as gmail.com) and you confirm or correct them, or type `none` and confirm that your company has none. An agent gets `domains_instructions`: plain sentences telling it what to ask its user and which command to run with their answer. Nothing in a new workspace is analysed until a person has confirmed them.
-  - The session is saved in `credentials.json` in the config folder, readable by you only.
+  - The session is saved in `credentials.json` in the config folder. Tokens are stored as local JSON, not in an OS keychain; passwords are not saved. Unix directories use mode `0700` and files `0600`; Windows uses the account's local application-data folder and its inherited access permissions.
   - The API checks the session on every call. The CLI renews it once it is past half its 30 days, so it stays signed in while you use it; if the API refuses it, the CLI renews once more, and otherwise asks you to sign in again.
 - `closedloop whoami`: who you are signed in as, your workspace (role and plan), the other workspaces you belong to, the region, when and how this computer signed in (an email code, or Google, Microsoft, Okta or SAML SSO, or a password, in the browser), and when the sign-in ends if the CLI is not used.
 - `closedloop status`: what is running now (company research, history imports with what is left and when they should finish, your own data still waiting or processing) and the onboarding checklist: company website, company research, email domains, product structure, a source, history imported, and the optional goal and team. Each open step names the command or the place in the app for it; a part the CLI could not read shows as unknown. No insights here: see `closedloop insights`.
@@ -98,8 +99,79 @@ Every command does only what the person may do in the app, and the API decides:
 
 ## Settings
 
-- `CLOSEDLOOP_API_URL`: the API to talk to. Defaults to the production API (`https://api.closedloop.sh`); existing EU accounts sign in through the EU API automatically. Use `http://localhost:3017` for an API running on your machine.
-- `CLOSEDLOOP_CONFIG_DIR`: where the CLI keeps its files. Defaults to `$XDG_CONFIG_HOME/closedloop`, else `~/.config/closedloop`.
+- `CLOSEDLOOP_API_URL`: the API to talk to. Defaults to the production API (`https://api.closedloop.sh`); existing EU accounts sign in through the EU API automatically. Use `http://localhost:3017` for an API running on your machine. An explicit API selects the deployment for sign-up and skips the production region question. Combining it with `--region` is a usage error; unset it to choose a production region.
+- `CLOSEDLOOP_CONFIG_DIR`: explicitly selects the folder for saved sign-in and settings; it takes precedence over every default.
+- `XDG_CONFIG_HOME`: when explicitly set, retains the existing `$XDG_CONFIG_HOME/closedloop` location on every platform.
+- Otherwise the default is `~/.config/closedloop` on Linux, `~/Library/Application Support/closedloop` on macOS, and `%LOCALAPPDATA%\closedloop` on Windows (falling back to the account's `AppData\Local` folder).
+
+On the first use of a new native default, the CLI copies an existing
+`~/.config/closedloop` folder to the new location if that location does not yet
+exist. The copy is published only when complete; original files remain in place.
+An existing destination is authoritative, including after logout, so an old
+copy cannot silently restore a removed sign-in. Explicit directory overrides do
+not trigger migration. Treat retained copies and backups as credentials too.
+
+The earlier API-key CLI's `config.json` is retained during installation and
+upgrades, but its team API key does not prove a person's identity: run
+`closedloop login` to sign in. Existing person sessions from version 0.3.0
+are preserved; team API keys are never converted into a person's session.
+
+## Upgrade and troubleshoot
+
+```sh
+npm install --global @closedloop-ai/cli@latest
+closedloop --version
+cl --version
+closedloop whoami --json
+```
+
+Upgrading replaces the installed package and preserves the separate config
+folder. Uninstalling the package also leaves that folder intact; use
+`closedloop logout` when you want this computer to forget its current sign-in.
+Logout also cancels pending email and browser sign-in requests. It does not
+revoke sessions on other computers or remove retained migration backups.
+
+To return to an earlier compatible version, install its explicit version with
+`npm install --global @closedloop-ai/cli@<version>`. The API can require a newer
+minimum version; in that case follow the `upgrade_required` hint. If npm fails
+during an upgrade, check both commands' versions and repeat the installation
+before assuming the package changed successfully.
+
+- `not_signed_in` or `session_expired`: run `closedloop login`; the CLI renews an existing session automatically when possible.
+- `region_required`: choose `--region us` or `--region eu` before creating a new account in a noninteractive flow. `region_check_failed` means the CLI could not establish whether an account already exists; retry or choose a region explicitly. Existing accounts still sign in in their original region.
+- `config_invalid`: back up the named JSON file and follow the recovery hint; the error never prints its contents. `closedloop logout` can remove damaged credentials and pending sign-in files.
+- `config_write_failed`: check folder permissions and free disk space; a failed replacement keeps the previous saved file.
+- `config_busy`: wait for other CLI commands to finish and retry. If a process stopped while holding a lock, inspect the named lock and confirm no CLI process is using it before removing it.
+- `config_migration_failed`: use `CLOSEDLOOP_CONFIG_DIR` to select the original folder; the original files were kept.
+- `session_changed`: a logout or newer sign-in took precedence while a request was running; repeat the command with the current sign-in. A delayed response does not restore a cancelled login.
+- `unknown_number`: list again in the current account and workspace, then select its number; saved numbers are not portable across accounts or workspaces.
+- `api_unreachable` or `api_timeout`: check connectivity and retry; inspect an ingestion failure's accepted-record hint before resending a partially sent batch.
+- `rate_limited`: wait for the delay in the hint; the CLI does not automatically repeat a write.
+
+On Windows desktop editions, Windows PowerShell 5.1 starts with the `Restricted`
+execution policy, which refuses the `closedloop.ps1` launcher npm installs:
+`closedloop` in PowerShell then fails with "running scripts is disabled on this
+system". Run `closedloop.cmd` (or `cl.cmd`) in PowerShell, use Command Prompt,
+where `closedloop` works as is, or allow local scripts for your account once with
+`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
+
+The JSON options (`--rule`, `--segment` and `--calc`) take inline JSON, a file path,
+or `-` for standard input. On Windows, give a file. Windows PowerShell 5.1, any
+PowerShell running `closedloop.cmd`, and Command Prompt remove the double quotes from
+JSON typed in a command: in Windows PowerShell 5.1, `--rule '{"of":"customer"}'`
+arrives as `{of:customer}` and fails with `invalid_rule`. Save the JSON in a UTF-8
+file instead, for example with
+`Set-Content rule.json '{"of":"customer"}' -Encoding UTF8` in PowerShell, then run
+`closedloop segments preview --rule rule.json`. The commands the CLI suggests on
+Windows pipe their JSON in, as in `'{"of":"customer"}' | closedloop segments preview --rule -`,
+and write it in plain ASCII with other characters as `\u` escapes, because Windows
+PowerShell 5.1 sends piped text to a program as ASCII.
+
+Browser and clipboard helpers need the OS tools and a desktop session. On a
+headless host or in a restricted session, follow the printed sign-in link and
+code instead. Path simulations alone do not verify desktop behavior on every
+OS edition; Windows Server guest coverage does not establish Windows desktop
+coverage.
 
 ## Principles