@aopslabs/aops

AOPS CLI and terminal setup application. The package brings the exact compatible local Server runtime, but remote-only users can use the CLI without configuring or starting that local Server.

npm install --global @aopslabs/aops
aops
aops --help
aops setup --help
aops setup ai
aops setup guide
aops setup init
aops server status --json
aops assets

That one command also installs the exact compatible @aopslabs/aops-server runtime. npm installation itself never starts services or runs migrations; aops setup init is the explicit first-time setup boundary.

The source repositories remain private. Customer-required runtime dependencies may also be published as public npm packages so ordinary installation never needs private registry credentials; this does not grant an open-source license.

The former npm package line is frozen at @aopslab/[email protected]. Do not publish later CLI versions under that package name.

aops is the primary executable. The aops-cli executable remains an exact backward-compatible alias, while new npm releases use the @aopslabs/aops package name. aops server ... operates the local Server. Open /ui on its configured origin, normally http://127.0.0.1:5900/ui, for Cockpit. There is no separate Cockpit service or port. A healthy Server row in the TUI links to that exact URL, including a custom configured port.

Before updating an installation with the old separate Cockpit, follow the upgrade and retained Chat recovery guide. Prepare browser recovery while the old serving path is available; merely opening the new origin cannot recover keys held in the old browser namespace.

On Windows x64, macOS arm64 and Linux x64, parameterless aops opens the bundled one-page Rust TUI. Intel/Rosetta macOS and other unsupported native targets use explicit CLI commands instead. Explicit commands retain the same CLI behavior on every supported platform. When stdin or stdout is not an interactive terminal, parameterless aops prints short CLI guidance instead of trying to draw the TUI. aops setup prints its subcommand help instead of opening a second interactive menu. The Rust TUI owns the operator setup experience, while explicit setup subcommands remain stable engines for the TUI, agents, and automation. aops setup ai prints a safe prompt that can be handed to Codex, Claude, or another terminal AI agent. The prompt routes the agent to the packaged aops-install skill and keeps secrets in documented environment variables or private files instead of chat or argv.

The default trusted-local server remains bound only to 127.0.0.1:5900. It does not trust LAN or Tailscale interfaces. AOPS Server serves its API and Cockpit /ui on that same origin. The root URL redirects to /ui/projects. Community no longer embeds a non-loopback identity provider, password store, refresh-session runtime, or first-admin bootstrap. Repair a legacy local environment without putting its PostgreSQL URL in argv:

AOPS_PG_URL='<private-url>' aops setup server-env --auth trusted-local \
  --yes --json

The managed block is rewritten as trusted-local; retired JWT, encryption, and bootstrap keys are removed without being printed. Local setup exposes one security mode: trusted-local with loopback. Remote identity is owned by South and consumed only as a separate CLI target using remote-session. External targets require HTTPS and system-ca; plain HTTP has no remote exception.

aops target add --name remote --api-base-url https://aops.example.com \
  --auth-provider remote-session --tls-policy system-ca --apply
aops target doctor remote --json
aops target use remote --apply
aops auth login --target remote
aops auth status --target remote
aops auth logout --target remote

For one compatibility release, target configuration input authv2-jwt-session is accepted and immediately canonicalized to remote-session; persisted current configuration uses only the canonical name. Existing local AuthV2 tables remain historical/read-only. Use aops auth legacy-export for a credential-free deterministic identity and role export; every migrated user must authenticate again through South.

aops auth logout --target remote --local-only deliberately clears only the local encrypted credentials when remote revocation is unavailable.

aops setup init is the argument-driven setup engine used by the TUI and automation. Without --apply it inspects readiness. Path 1 uses an existing operator-owned PostgreSQL connection; path sqlite uses a server-local SQLite file; path 4 selects an existing aops Server. It never installs, provisions, starts, stops or removes PostgreSQL, databases, or roles. It may apply only aops migrations to the selected database.

The TUI is a compact System Check page (minimum 96x30), with short Server and Database Configure dialogs and row-specific Fix actions. Server defaults to http://127.0.0.1:5900. Database Test checks a candidate without saving, creating or migrating a database, or stopping services. Connect is separate and confirmed. PostgreSQL supports form/connection-string input with explicit TLS and only the password masked. SQLite uses an absolute server-local file and requires Node.js 22.16+ transaction-state and backup support; its Test may create WAL coordination sidecars when checking an active database. Switching databases keeps the prior profile/data; it does not transfer data. Other computers connect to the Server, not to a network-shared SQLite file. Assets and CLI have Check/Update only. Internal prepare/apply is not a TUI menu. F3 shows sanitized commands/results and the full log path. Long updates show elapsed seconds and stages, warn about 5–10 minutes, and close the old TUI after verified success is acknowledged. Errors stay on their affected rows.

Local setup verifies migrations, Server/Cockpit health and bundled public assets. It does not seed starter/demo user data, select a working discipline, or require a server-side catalog bundle. Explicit catalog-release commands remain separate. CLI db backup, db list, db restore and db which are not TUI pages. Native PostgreSQL and SQLite backups retain their separate formats. SQLite db backup --portable exports all aops data for one-way replacement of a compatible prepared PostgreSQL target. Stop the selected aops Server/Cockpit first and explicitly confirm data rewind; restore verifies a mandatory target undo and leaves services stopped. No selection, merge or PostgreSQL-to-SQLite transfer is supported. Read the canonical CLI User Guide and nested help.

Every JSON setup preview includes a deterministic, mutation-free installer contract. installerPlan.contractVersion must be exactly aops.setup-installer-plan/v2, installerPlan.operation identifies the lifecycle action, and installerPlan.planId binds both fields plus the exact selection and readiness material. Human clients such as AOPS TUI reject an unsupported contract or operation before applying, then pass the identity back with --plan-id. A changed contract, source, selection, or readiness snapshot therefore fails before setup mutates anything. Existing scripts may still use the legacy direct --apply form, while new automation should validate the contract and bind preview and apply explicitly:

Use path 1 with a privately saved PostgreSQL URL and the tested TLS policy, path sqlite with the selected server-local file, or path 4 to connect this CLI to an existing aops Server. Inspect aops setup init --help for each path.

Setup path 4 connects the CLI to an existing AOPS Server without installing or operating local PostgreSQL or server processes. It saves and selects the named target, checks that exact endpoint, and continues with the browser-approved remote-session device login when required:

aops setup init --path 4 \
  --api-base-url https://aops.example.com \
  --target-name remote \
  --target-auth-provider remote-session \
  --target-tls-policy system-ca

The existing-PostgreSQL path supports managed providers such as Supabase and Neon. Readiness compares only the migration-derived AOPS-owned table, column, key, constraint, and index contract; column order, audit timestamps, local receipts, and unrelated provider objects do not affect the result. The six domain migration roots (sys, agentspace, docman, projectman, chatv3, and tasker) remain resumability evidence rather than a second schema authority. When that semantic structure is already exact, readiness does not inspect historic SQL or journal bytes; executable bundle validation occurs only when pending DDL must run. Provider schemas, extensions, global event triggers, and unrelated public objects are preserved. Normal setup does not require backup evidence, hash application rows, pre-lock AOPS tables, or rewrite provider-managed grants. Eligible DDL runs transactionally under a non-waiting migration lock and the live semantic schema is read back before success. Optional audit-write failure does not invalidate that result.

The CLI package depends exactly on the compatible @aopslabs/aops-server release, so local installation remains a single npm command. Remote users may leave that local runtime unconfigured and connect only to their selected remote target. No customer path requires Git or a source checkout. Advanced developers can still run an explicit checkout with --source-root. A stopped installation can move between valid checkout/npm roots through the same setup command without reset or duplicate rollback copies; same-root npm byte drift still requires reinstalling the package.

aops setup guide prints the packaged agent installation skill before any server is initialized. The CLI bundles the verified public asset descriptor and archive. Explicit asset commands install or update managed aops skills, user guides, disciplines and roles for registered agent runtimes.

Parameterless TUI startup reconciles missing or older bundled assets, preserves newer installed releases, and never replaces unrelated user assets. npm postinstall does not change agent homes. The assets row displays Current and latest compatible release and offers Check/Update. Asset versions are independent from CLI versions. Use aops assets --help for exact options; --target all selects all registered runtimes.

Server data, configuration, credentials, logs, and lifecycle state are stored outside npm's package directory. PostgreSQL remains operator-owned.

Opening the TUI does not by itself start or stop the Server. Use its explicit actions or aops server commands. Opening the healthy Server link is a browser navigation and leaves lifecycle control with those actions.

The npm package includes launchers/aops-server.sh and launchers/aops-server.ps1 for running the installed server in the current terminal with live logs. They invoke node dist/launchers/server.js by a package-relative path, reuse the normal installed lifecycle, and stop on Ctrl+C or terminal close. The scripts accept --instance and --data-root; they contain no credentials and do not resolve or invoke aops through PATH.