lagora-cli

Lean npm distribution of the Legato Agora CLI. The npm package is lagora-cli (unscoped); the executable remains lagora. Nothing has been published, so installing from the public registry doesn't work yet. Until a release exists, install from the internal GitHub release tarball or run ./bin/lagora from a repository checkout as described in the root README.

After a public release:

npm install -g lagora-cli
lagora login
lagora help

lagora login opens the browser flow described in the root README and stores a CLI-scoped token; nothing about login changes in the npm build.

For a browserless remote interactive terminal, use lagora login --device-code [--api-url <url>]. Open the printed verification URL on another device, enter the human code, and approve there. Then confirm the returned company and activity profile in the CLI before it exchanges or saves a token. No local browser or callback listener opens. A TTY is required (SSH: ssh -t); --yes is not supported. Ctrl-C cancels; authorization lasts at most five minutes. Normal lagora login remains the browser/loopback flow.

Requires Node.js 22.16 or newer. Remote login, reports, issue commands, Playground upload/status, SDK administration and feedback use compiled Node.js, without Next.js, React, tsx, Bash, curl or Python runtime dependencies. Login opens the system browser and prints the URL for manual use if opening fails. Saved login targets and LAGORA_CONFIG / XDG_CONFIG_HOME remain supported.

lagora report --store retains the existing portable shell writer and requires Bash, Python 3 and standard Unix utilities. It preserves duplicate merging, artifact collision handling and optional --auto-lowering. Local reads and mutations remain isolated from the working directory's other stores. playground validate requires Python 3. Real lowering/fSIM and SDK preparation also require the separately installed platform-specific SDK, Python and its build tools; this package does not install them or promise Windows portability for these optional paths. No live SDK build or production service is exercised by the package tests. Remote reports do not query GitHub CLI identity.

Self-update

The installed CLI keeps itself current from the npm registry. Nothing runs in the background: no daemon, cron entry or extra dependency.

Automatic

After an ordinary command finishes and prints its own output, the CLI checks for a newer stable release and installs it if found. The original command's exit code is preserved either way. Checks happen at most once every 24 hours per install prefix, and a failed or offline check counts toward that window, so a machine without network access sees at most one bounded attempt per day. Timeouts are short: the version lookup is capped at 4 seconds and the install at 45 seconds, with no retries.

Turn it off in one of two ways:

lagora update --disable   # persisted; lagora update --enable turns it back on
LAGORA_AUTO_UPDATE=0 lagora report ...   # per process; false and off also work

The persisted setting lives in $XDG_CONFIG_HOME/lagora/update.json (~/.config/lagora/update.json by default). It's separate from the login config, which the updater never reads or writes.

Manual

lagora update          # check now and apply a newer stable exact version
lagora update --help

lagora update ignores the 24-hour throttle and the disabled setting, prints a JSON status line, and exits 0 when it updated or was already current, 1 when the install is unsupported, another updater holds the lock, or the update failed. Reasons are sanitized codes; raw npm output and credentials never appear.

Supported installs

Self-update, automatic or manual, only touches a canonical npm install -g of lagora-cli on Unix where the global prefix, bin link and package directory are owned and writable by the current non-root user and match npm's configured global prefix. Everything else still runs every ordinary command but never updates itself and makes no registry update requests:

• sudo or root installs
• Windows
• npx
• project-local dependencies
• npm link or a repository checkout
• read-only prefixes

npm itself is invoked with --ignore-scripts, --engine-strict and an exact validated version, using your configured registry, .npmrc and npm-managed auth. CLI and chat tokens are kept out of npm's environment.

Disk footprint and cleanup

Each applied update is staged inside the prefix and then kept as an immutable release under <prefix>/.lagora-update/releases/<uuid>. Only the small global launcher file is switched, atomically, so commands that are still running, or suspended, keep the assets they started with. Old releases are intentionally not garbage-collected: a paused process may still need them. Each retained release is roughly the size of one unpacked package, about 0.6 MB at the current version, so the directory grows by that much per update.

To reclaim the space:

1. Make sure no lagora process is running or suspended.
2. Reinstall normally: npm install -g lagora-cli.
3. Remove <prefix>/.lagora-update (find the prefix with npm prefix -g).

npm uninstall -g lagora-cli alone leaves .lagora-update behind; remove it by hand as well when uninstalling for good.

Known limits: the updater's lock doesn't coordinate with a separate npm install/uninstall you run at the same time, and a hard kill between the launcher switch and the manifest refresh can leave npm ls -g showing a stale version while the CLI itself already runs the new release. Both are recovered by an ordinary reinstall.

Build and test from this repository

npm ci
npm run build:cli
npm run test:cli
npm run pack:cli

The build reuses the repository's esbuild and compiles only the CLI dependency graph. dist/ and this README plus the manifest are the only shipped files. Explicit asset allowlists exclude tests, environment files, local data and repository evidence. There are zero runtime npm dependencies and no install lifecycle script. The root website remains private and independently built.

The runtime test creates a real tarball with npm pack, installs it globally under a temporary prefix outside the repository, then runs that installed lagora with temporary HOME/config/data directories and loopback APIs only. No npm credentials or registry publishing are needed.