@truealter/cli

The alter command line. Log in once, stay authenticated across your tools.

~alter (formal: ~Alter) is the personal identity agent. This CLI binds your terminal session to your ~handle and exposes the small surface of commands you need day-to-day.

Install

npm i -g @truealter/cli

Node 20 or newer.

Commands

Run alter with no arguments for an interactive menu. Direct verbs stay available for scripting and habit.

Getting started

• alter login — bind this shell to your ~handle. Writes session state to ~/.config/alter/session.json.
• alter login --dry-run — walk the onboarding flow without persisting any session state. Useful for voice-pass review and demos.

Pairing sources

• alter pair — interactive picker over the full connector registry.
• alter pair <id> — pair a specific source. Supported ids: linkedin, github, twitter, spotify, strava, discord, arena, website, obsidian. Registry is server-driven, so new sources appear without a client release.
• alter connections — list what you've paired.
• alter unpair <id> — disconnect a paired source.

Identity + rhythm

• alter whoami — print the currently logged-in ~handle and session metadata.
• alter status — identity, attunement, org, and reachability at a glance.
• alter wallet — show the registered Identity Income payout address; prompts to register one if missing. Requires engagement level 3 or higher. ALTER never custodies funds — you bring your own EVM address (EOA, smart account, or multi-sig) and the AlterRouter contract routes x402 earnings directly to it.
• alter mirror — render today's line only when attunement has one to surface. Not a scheduled feed; stays silent off-cadence.
• alter brief — print an Org Alter morning brief to stdout. Requires mcp-org-alter to be installed separately (see Configuration).

Account

• alter passkey add | list | remove <id> — manage passkeys.
• alter password change | reset — rotate or reset the account password.
• alter sessions revoke-all — invalidate every active session for your account.
• alter logout — clear the local session.

Run any command with --help for flags.

Configuration

Two environment variables are honoured:

• ALTER_API — override the ALTER backend base URL. Defaults to the production endpoint. Set when running against a staging or self-hosted deployment.

• ALTER_ORG_MCP_CMD — shell command that launches the Org Alter MCP server. Required for alter brief. Example:

  export ALTER_ORG_MCP_CMD="npx -y @truealter/mcp-org-alter"

alter brief will not spawn anything unless ALTER_ORG_MCP_CMD is set, and will exit with a clear error if it is missing. There is no implicit path fallback.

Session state lives at ~/.config/alter/session.json. The file is created on alter login and removed on alter logout.

Status

Pre-1.0. Interfaces may change between minor versions until 1.0.0 ships.

alter brief requires the mcp-org-alter package to be installed and reachable via ALTER_ORG_MCP_CMD. That package is distributed separately.

The onboarding copy in src/onboarding/observations.json is held until a voice-pass is committed by the Sovereign-tier holder. A published build without that pass is not representative of the finished experience.

Contributing

After cloning, npm install runs the prepare script which sets core.hooksPath to .githooks/. That wires the D-ID8 identity-trailer hook (per Strategic Decisions Register 9 Apr 2026) so every commit you make from this repo carries the Acted-By: and Drafted-With: trailers automatically. The hook reads your ALTER session at ~/.config/alter/session.json (run alter login once); it is silent when the session is missing or jq is unavailable, so a contributor without an ALTER session still gets a normal commit. The CI verifier catches missing trailers at PR time (warn-only during the Rung 1/2 migration window).

If you skipped npm install (e.g. you fetched the repo via tarball, or you use a package manager that doesn't run prepare), wire the hook manually:

git config core.hooksPath .githooks

License

Apache-2.0. See LICENSE.