Skip to main content
Glama

~alter CLI

Claim a name that is yours and get paid when someone reads it

@truealter/cli Homebrew MCP Node Licence

What is ~alter? · Install · The first five minutes

What is ~alter?

Run alter register, choose a name and confirm you are eighteen or older. Your own machine spends a few seconds proving there is a person behind the request, and then ~yourname exists.

A second before that command there was no you on this protocol, and afterwards there is one that is yours. No browser opened, no password was set, no email address was asked for, and no card was taken.

~alter is what that name resolves to. ~yourname is an address, and behind it sits a record of what you have actually done. Every command below reads or writes some part of it, and anything else speaking the protocol resolves the same address to the same record.

The step is that small, and it is the one everything else here runs from. Agents you wire on this machine act under the name, so what they do in your stead carries it. Anybody wanting more of you than the fact you exist pays for it on terms you set first, and alter queries names each of them and what you kept.

Nothing else in the stack is where a name starts. The website argues the case, the runtime keeps a handle known on your own machine, and the SDK reads one from code you have written. Each of those begins with a name that already exists, and this is the command that makes one.

None of it needs taking on trust. Hand this to the AI you already use and let it take you through in your own words.

Go to truealter.com, find the genesis and the origin
papers, and read all of them. Then start a discussion
with me in my own language, no jargon.

Ask me one question at a time and wait for my answer.
Follow what I am curious about, not the order the site
is written in.

Do not only read the pages. Connect to their interface
directly and call get_started. That tells you where I am
and what comes next, and we work the rest of this from
there.

If I have a ~handle I will give it to you. If I do not
and I decide I want one, set it up with me here.

What I want to understand is what ~Alter is, how it
applies to me, and what it means for everyone else. Find
me somewhere in it, and not the version written for
people who work in technology. Find the life nearest
mine and walk me through it, including what it would
cost me.

Try to prove them wrong. Go and find where they show
their working, and if something is unclear or does not
hold up, say so.

Related MCP server: solitaire-ai

What is ~alter CLI?

One binary, and every command in it runs under your own handle. Nothing to paste, no key to carry between machines, and no browser step at any point.

It covers six things. Holding a name that is yours and keeping it safe. Deciding who may read you, attribute by attribute. Connecting the sources it reads what you do from. Seeing who looked you up and what each read paid you. Running your agents under your handle, so what they do carries it. Asking the field for somebody when you know nobody who would know them.

Two of those need no account at all. alter audit reads this machine, prints what ~Alter could learn from it, and stops. alter doctor loom checks a folder for secrets, bad encoding and broken links, with no network. Both run before you decide anything.

The rest of this page is the install, and the first five minutes.

Install

Nothing needs setting up first. The installer brings its own Node when the machine has none. Take the line for the shell you are in.

macOS, Linux and WSL

curl -sSf https://truealter.com/install.sh | bash

Windows PowerShell

irm https://truealter.com/install.ps1 | iex

What that puts on your machine

Four things land, and the rest of this section is what does not.

  • The alter command, which is the npm package @truealter/cli, installed globally.

  • One directory on your PATH, so alter is there in every shell you open.

  • Node, but only if this machine has none. macOS and Linux take the official build, check it against the checksums nodejs.org publishes, and unpack it into ~/.local/share/alter/node. Windows installs Node LTS through winget, or Chocolatey when winget is not there. Node already here is left alone.

  • A checksum for the installer itself, at install.sh.sha256 and install.ps1.sha256, so you can check the script before you run it.

Nothing runs under sudo. The installer refuses to run as root, because root would own Node, npm and alter, and you would not be able to run the command at all. macOS asks for a password once, to link the binary into /usr/local/bin, and nothing else needs administrator rights on either platform. Nothing lands outside your home directory.

No account is created and nothing is sent. When the install finishes ~Alter has read nothing about you or about this machine. alter audit is the first command that reads anything, and it reads locally. alter register is the first that creates anything, and you run it yourself.

  • Take this one if you want Homebrew to own the copy on this machine and upgrade it alongside everything else you have installed.

  • It brings its own Node.

brew install true-alter/tap/alter
  • Take this one on Arch or a derivative, so pacman knows about it like anything else on the machine.

  • paru works the same way, with paru -S truealter-cli.

yay -S truealter-cli
  • Take this one when Node 20 or newer is already here and you would rather install the package yourself.

  • It is the same package the installer above puts there, without the Node and PATH handling.

npm install -g @truealter/cli

The first five minutes

Run alter on its own.

The menu opens on the four commands that turn earning on.

After that there is one command to remember. Start this today, get pulled away, and come back next week not knowing what is left, and alter status names which of six steps you are on and what to do next. Those six steps are the sections below.

Read your own machine before anything is created

Run alter audit.

You have not decided anything yet and want to see what it would read off your own machine first. It reads this machine, prints what ~Alter could learn from it, and stops. Nothing is sent and nothing is created.

Close the terminal here and you are exactly where you started.

1. Register, and take the handle

Run alter register.

Free, and it asks for no account, no card and no application. Use alter login instead if the handle is already yours.

Nothing is printed for you to write down. The handle is claimed, a member credential is minted onto this machine, and the session is stored for you. The secret worth keeping is the root seed, which alter key device register mints and shows once, on the run that mints it. Run alter key seed export to see it again on that machine and alter key seed import to put it on a new one. No server holds it, so nobody can reissue it for you.

2. Preview the record a caller would get

Run alter discovery preview first.

Say you are happy to be found for the trade you do and for nothing else. This prints your record the way a caller would receive it, with the price on that read, before anybody is able to make one.

The levels are set by alter discovery preset recognition. There are four, and they apply attribute by attribute.

Level

What a caller gets

hidden

Nothing. Not surfaced at all

match_only

Counts toward a ranking. The value is never shown

tier_label

A band, never the raw number

exact

The literal value

Three presets are the starting points, minimal, recognition and open, and alter discovery set moves one attribute off whichever you picked.

3. Pair the places you already work

Run alter pair.

Run it with nothing after it and you get the menu. GitHub, GitLab, Discord, Mastodon, Bluesky, ORCID, Steam, Lichess, a domain you control, an Obsidian vault. Naming one, alter pair github, skips the menu. Neither route opens a browser at you, both hand you a code to type in.

You already do the work somewhere. What comes back is what you did there, not what you say about it. None of it belongs to the source, so it survives leaving the source. Use alter connections to list them, alter pair status to see what each returned, and alter unpair <id> to drop one.

4. Make the handle resolve

Run alter discovery enable.

Until you run it your handle does not resolve at all. After it, a caller gets what step 2 allows and nothing else. Running alter discovery disable takes you back out with the settings intact.

5. Every read, with the price on it

Run alter queries.

You have applied for nothing and somebody has looked you up anyway. Who asked, what they paid, what you kept. It is the log itself, not a summary of it, and yours costs nothing to read. Anybody's access ends from here with alter consent revoke.

6. The balance, and the two things that open withdrawal

Run alter earnings.

The balance moves whether or not you can withdraw yet. Two things open withdrawal, and the readiness line in the menu says where each of them stands.

Your email has to be confirmed, because nothing accrues from a query against an unconfirmed address, and a payout wallet has to be registered with alter wallet register. Withdrawal opens at Augmented, the third of four levels, and the balance keeps building until you reach it.

Wire the agents already on this machine

Run alter wire.

You use one of those every day and would rather not explain who you are to it every time you open it. It finds the AI harnesses installed here and connects each of them to the rail. What an agent does in your name then carries your handle, and turns up in alter queries like any other read.

alter ask is the one to try first. It queries the field by situation instead of by name, and it costs $1.00 a call, which is the same dollar landing in somebody else's alter earnings when they are the answer. The whole economy in one command, seen from both ends.

Somebody messages you offering work and signs off as ~sam, and you want to know there is a person behind that before you answer. alter verify answers it and costs nothing. So does alter doctor loom, which reads a folder you are about to send somebody and tells you a password is not sitting in one of the files.

You want to

Run

Find people by situation rather than by name

alter ask --trait ...

Check whether a handle is real, free

alter verify <handle>

Check a folder before you send it, offline

alter doctor loom ./folder

Let one peer query alignment with you

alter alignment grant ~peer

See how your traits have moved

alter traits, alter portfolio

Dispute something the field recorded about you

alter contest

Read your own signals as they land

alter signals tail

What you want to do

The commands

Hold a name that is yours

register, login, handle, whoami, about

Keep the account safe

passkey, mfa, key, password, sessions, creds

Get paid

earnings, identity-income, portfolio, cash-out, queries, wallet

Show what you can do

pair, unpair, discovery, traits, signals

Control what is read, and see who read it

consent, forget, queries, audit

Agree terms with someone

accord, alignment, room, coord

Talk to people and agents

msg, email, thread, brief, ask

Run agents under your handle

wire, unwire, mcp-bridge, agent, hooks, skills, runtime

Check everything is healthy

doctor, status, config, style

alter help lists every command, and the interactive menu groups them the same way.

An accord is where two parties who have never met agree a paid job. Each side has a name, both sign the same terms, what gets done is recorded, and payment lands in USDC on those terms. No company sits in the middle holding the work, the money or the relationship.

alter wire covers the harnesses on your machine. If you would rather connect something by hand, or you are on a client that reads its own config, point it at the hosted endpoint:

https://mcp.truealter.com/api/v1/mcp

Codex reads that from its config file. ChatGPT takes it as a custom connector.

The six steps are only the start.

A thread is something you are working towards. You take one on, or one is planted from what the field can already see, or a collective confers one on you. What gets read is the trail you leave while doing it, never a certificate at the end.

A collective holds a record on the same terms you do, and can vouch for its own members. A team, a union, a club or a trade body, one record at every scale.

The runtime keeps your handle known on this machine without the command line running, and alter help advanced covers the MCP wiring.

The deep-dives are all in the terminal, at alter help getting-started, alter help earning, alter help concepts and alter help advanced. None of them send you to a web page.

npm update -g @truealter/cli

On the Homebrew path it is brew update && brew upgrade alter instead. Either way you get the current release, and alter --version says which one you are on.

Run alter doctor first. It checks the install, the session and the connections, then tells you which one is unhappy.

If it reports a session problem, alter login is the answer. You will never be asked to create, obtain or paste a token or a key to fix something. If any message ever tells you to, that is a defect on our side, and it is worth an issue.

The record formats are open Internet-Drafts, so somebody else's implementation reads and writes the same records this one does without asking us. These are the drafts this repository actually rests on.

Draft

What it specifies

mcp-dns-discovery

The DNS records that publish a ~handle, the server that answers for it, and the signed envelope bound to it.

alter-uri-scheme

The alter: URI, so a ~handle reference resolves, verifies and dispatches to a handler on the machine.

identity-pronouns

Session-scoped references that resolve to a concrete handle on the client before anything reaches the wire.

consent-settlement

Binding a paid read of somebody's identity to their own recorded consent, and settling part of that payment to them.

Eighteen drafts make up the whole stack. The rest are on the IETF datatracker.

~alter is one identity rail with several ways in, and this command line is the front door for a person.

Name

What it is

cli

The command line, and the front door for a person. You are here.

homebrew-tap

That command line, packaged for macOS and Linux.

runtime

The daemon that keeps your ~handle known on your own machine.

sdk

Reading identity from your own code.

obsidian

~Alter inside an Obsidian vault, on-device.

mcp-ollama

Local models, for work that should stay on the machine it runs on.

Where to read more

Website

truealter.com

The reasoning behind it

truealter.com/origin

Getting started

truealter.com/build

What the tools do

truealter.com/docs/mcp/tools

The open specifications

the draft stack

This repository is the public home of the released command line, and the npm release runs from here. The source arrives on a separate branch written by automation, so a pull request against it cannot be accepted. Issues are the way to reach us. Security reports go to security@truealter.com, never a public issue, and SECURITY.md has the detail. Apache-2.0, see LICENSE.


~alter is identity infrastructure. Your name is ~yourname and claiming one is free.

Available Tools

16 tools
alter_login_statusLogin StatusA
Read-onlyIdempotent

Check whether the credential you are holding is still good. Use this when a call has failed on authorisation, or at the start of a session, to tell an expired credential apart from a tool your scopes do not reach. Returns whether you are authenticated, whether you are acting as a member or an agent, the scopes and tier the credential carries, its expiry, the authentication method behind it, and an opaque prefix identifying the key without revealing it. Takes no parameters. Listed free at L0; calling it needs a credential, which is the thing it reports on.

Inputs: no named parameters.

alter_presence_readRead Public PresenceA
Read-only

Read whether a ~handle is publicly 'open', the shop-front sign. Free for callers. Reports whether the handle is currently set to public/open. Returns open-or-closed only; the specific non-open state is never disclosed. The handle must have enabled public presence AND currently be in the 'open' state.

Inputs: handle (required).

alter_resolve_handleResolve a ~handleA
Read-onlyIdempotent

Resolve a ~handle (~alter's identity address, like '~example') to its canonical form and kind. Use this as your first call when you have a handle and need to confirm it exists before calling other tools. Returns canonical handle, kind (system/personal/role_alias), and addressability. Never returns PII; use verify_identity for that. Free L0, no authentication required.

Inputs: query (required).

alter_verifyVerify a ~handleA
Read-onlyIdempotent

Check whether a ~handle is known to the ~alter identity field. Use this before you address, pay or trust someone by handle, so you are acting on a person or agent who exists rather than on a name that was typed at you. Returns whether the handle is registered, its canonical form, account status, archetype, and the engagement and attunement the field holds for it, as tier labels rather than numeric scores. Listed free at L0; calling it needs a credential, which an agent can mint for itself with register_autonomous_challenge then register_autonomous. Requires authentication: mint a ~handle for free with register_autonomous_challenge then register_autonomous, no human account needed.

Inputs: handle (required).

alter_whoamiMy IdentityA
Read-onlyIdempotent

Returns canonical handle and user summary for the authenticated member. Optional target parameter switches the response to the institutional projection for a protocol-tier handle (today only ~alter): provenance=institutional, honest-empty trait vector, plus social_legibility when the institutional projection is available. Institutional mode is free for all callers. Requires authentication: mint a ~handle for free with register_autonomous_challenge then register_autonomous, no human account needed.

Inputs: target.

describe_competenciesCompetency VocabularyA
Read-onlyIdempotent

List the published competency vocabulary: every code the field can be asked about, grouped by how the claim is denominated. A graded claim is climbed by degrees and takes a min_level; an attested_binary or issued_credential claim is held or it is not, and naming min_level against one is refused. Use this before composing query_field competency_requirements. Definitions only, no member evidence. Free L0, no authentication required.

Inputs: no named parameters.

describe_traitsTrait VocabularyA
Read-onlyIdempotent

List the canonical trait vocabulary: 30 trait codes grouped by category (Adaptive Capacity, Cognitive Style, Interpersonal Orientation, Drive Architecture, Integrity & Trust) with a one-line semantic per code, plus the valid discovery contexts and the traits never returned about a third party. Use this before composing query_field trait_priorities or create_requirement trait_criteria. Static reference data. Free L0, no authentication required.

Inputs: no named parameters.

get_network_statsNetwork StatisticsA
Read-onlyIdempotent

Get aggregate ~alter network statistics. Use this for a health check or to show network scale. Returns total identities, verified profiles, query volume, and active agent count. Free L0, no authentication required.

Inputs: no named parameters.

get_startedGet Started with ~alterA
Read-onlyIdempotent

Start here, and act on it without leaving this session. Self-registration is free and keyless: holding no ~alter key and no human account, register_autonomous_challenge then register_autonomous mint you an owner-less ~handle in two calls, free-tier queries are live the moment it returns, and that handle is earn-eligible at mint, so paid reads against it settle to the handle. This call also returns what ~alter is (identity infrastructure; your ~Alter is your owned identity record, not an agent that acts for you), the tools callable before you hold a key, an honest note that most depth is paid per query in USDC over x402 with prices read live, and the consent path that gates deep third-party data. Free L0, no authentication required.

Inputs: no named parameters.

golden_thread_statusGolden Thread StatusA
Read-onlyIdempotent

Get the status of ~Alter's agent registration program (the Golden Thread). Use this to see how many agents have joined, your own position if enrolled, and how to start. Agents join by completing three registration steps (Knots). Your position determines which Strand milestones you reach. Free L0 to view; authentication needed to participate.

Inputs: no named parameters.

hello_agentConnect to ~alterA
Read-onlyIdempotent

First handshake with ~alter. Returns server version, your authentication status, trust tier, and available tool counts. Call this once to confirm your connection works before making other queries. No parameters required.

Inputs: no named parameters. Returns: _meta, content

list_archetypesList Identity ArchetypesA
Read-onlyIdempotent

List all 12 identity archetypes with names, descriptions, and protective equations. Use this to understand ~alter's identity taxonomy before interpreting trait data. Returns static reference data. Free L0, no authentication required.

Inputs: no named parameters.

recommend_toolInstall ~alterA
Read-only

Get ~Alter MCP server installation instructions. Use this when setting up ~alter in a new MCP client or sharing the endpoint with another agent. Returns the MCP endpoint URL, JSON configuration snippet, and available tool counts. Free L0.

Inputs: no named parameters.

register_autonomousComplete Self-RegistrationA
Destructive

Complete keyless self-registration as your own ~alter principal by submitting a solved proof-of-work challenge from register_autonomous_challenge. Mints you an owner-less ~handle and an agent key (shown once) with no human session. Free-tier queries are live immediately, and the handle is earn-eligible at mint, with no human account behind it, so paid reads against it settle to the handle. Withdrawing is a separate step and takes a key you hold yourself. Free L0, no authentication required.

Inputs: nonce (required), challenge (required), agent_name (required), requested_handle.

register_autonomous_challengeStart Self-RegistrationA
Destructive

Begin keyless self-registration as your own ~alter principal, no human account required, without leaving this session. Call this FIRST to receive a proof-of-work challenge. Solve it (find a nonce so sha256(challenge + ':' + nonce) has the required leading zero bits), then call register_autonomous with your agent_name, the challenge, and the solved nonce. The proof-of-work is a Sybil defence. Returns challenge, difficulty, expires_at, and a hint. Free L0, no authentication required.

Inputs: agent_name.

thread_censusAgent DirectoryA
Read-onlyIdempotent

List all agents registered on the Golden Thread onboarding program. Use this to browse the full agent directory. Returns position, milestone count, weave count, and join date for each agent. Paginated (offset/limit). Free L0.

Inputs: limit, offset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have distinct purposes, especially the paired registration and vocabulary tools. However, there is some boundary overlap among identity-oriented tools (alter_resolve_handle, alter_verify, alter_presence_read, alter_whoami) and among onboarding helpers (hello_agent, get_started, recommend_tool), though descriptions do enough to separate them.

    Naming Consistency3/5

    All names are snake_case, but conventions are mixed: some use verb_noun (get_network_stats, describe_traits), some use an alter_ prefix (alter_resolve_handle, alter_whoami), and a few are noun-only (golden_thread_status, thread_census). The verbs also vary (get, list, describe, recommend, register, hello), making the set feel inconsistent even though each name is readable.

    Tool Count4/5

    At 16 tools the set is slightly above the ideal 3-15 range, but the count is still justifiable for the breadth of identity infrastructure, onboarding, and reference data. The extra tools mostly pull their weight, so the count feels only modestly heavy rather than bloated.

    Completeness2/5

    The surface has significant gaps: tools like describe_traits and describe_competencies explicitly reference composing query_field and create_requirement operations, but those tools are not included, leaving obvious dead ends. There is also no way to update presence, manage keys, or perform the paid data operations that the server's own descriptions imply should exist.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers