Archway

archway is the lightweight command-line client for an Archway service. It contains no translation engine, analysis engine, or server implementation.

Portable IR revision 21

This client prefers portable IR revision 21 and still reaches older engines, and so older revisions, with --engine; archway health lists the hosted engines and the revision each writes. Engine selection defaults to the engine pinned by this CLI release, unless you set --engine or ARCHWAY_ENGINE.

• archway translate sends a revision-21 engine one module and writes its response: the module's document (or its error), its source sha256 and the document's fingerprint. A module that fails exits with status 1.
• archway ir guide prints revision 21's complete specification, and archway ir catalogue its record catalogue as data.
• Moving from revision 9 is a retranslation, not a field update: the change log lists every change with the consumer action and an example.

Installation

Install the command into an isolated environment:

uv tool install archway      # or: pipx install archway

Signing in

archway login

This opens a browser to sign in with your Archway account (--no-browser prints the address and code instead, for a machine without one). You stay signed in: the client keeps your sign-in in a private file (~/.config/archway/cli-credentials.json) and renews its short-lived tokens itself. archway whoami shows who you are signed in as; archway logout forgets the sign-in.

Scripts that run unattended use their own machine credentials instead (a WorkOS M2M application your administrator issues):

export ARCHWAY_CLIENT_ID="client_..."
export ARCHWAY_CLIENT_SECRET="<secret>"

ARCHWAY_TOKEN, a raw bearer token, overrides both; it is meant for tests.

Agents

An agent (a Claude session, an overnight job) should act as itself, not as you. It registers and you claim it:

archway agent register nightly --email you@example.com   # prints a link for you
archway agent claim nightly <code>                        # the code the link showed you
ARCHWAY_AGENT=nightly archway translate module.py         # or: archway --agent nightly …

The agent gets its own Archway identity, capped by your access, and renews itself while it runs at least monthly. archway agent list shows the agents on this machine; archway agent revoke nightly revokes it in Archway for good (you must be signed in; services refuse it within a minute) and forgets it here.

All of your agents act as one Archway identity, <you>-agents, capped by your access; each agent is a separate credential of it, so records show which one acted and each can be revoked alone.

Configuration

The client talks to https://engine.archway-labs.ai unless ARCHWAY_URL (or --server) names another Archway service.

A service can host several engine commits. archway health lists them; without further configuration this CLI release's pinned engine answers (see archway capabilities). To use another one, pass --engine <commit> (or set ARCHWAY_ENGINE); a unique prefix of at least 7 hex digits is enough:

archway --engine 27913a47 translate example.py

To follow the service's latest release instead of this CLI's pin, use latest, for example by setting ARCHWAY_ENGINE=latest in your shell profile. The latest release is the engine the newest CLI release pins, and it also answers requests that name no engine.

Flag selection takes precedence over ARCHWAY_ENGINE, then the release pin. This applies to both translation commands and archway mcp serve, including custom server URLs. An unavailable engine fails clearly; there is no fallback to an older engine. In the Python transport API, ArchwayClient(..., engine="latest") (or engine=None, which names no engine) uses the latest release; pass DEFAULT_ENGINE_SHA from archway_client.client to adopt the CLI release target. Analysis sessions are bound to one engine and need a full commit.

Each translation records the engine that produced it as engine_sha.

Releasing a client

Select an already deployed, immutable engine commit in archway_client.client.DEFAULT_ENGINE_SHA and its documented PORTABLE_REVISION. The engine commit is independent of the client release commit, avoiding a circular self-reference. Update the pin deliberately when advancing translation behavior; client-only releases can retain it. The PyPI release workflow checks that the public service hosts that exact ready engine as its latest release (default engine) and advertises the preferred revision before publication, so a release that advances the pin follows the deployment that makes its engine the latest. Keep historical engines available for older pinned clients. Never repoint a pin or automatically substitute an available engine.

The health check does not require signing in:

archway health

Discover the installed client's current commands and agent guidance:

archway --help
archway agent-guide
archway capabilities --format json

Translate one Python file:

archway translate example.py

Specify its dotted module name and write the IR response to a file:

archway translate src/example.py \
  --module-name package.example \
  --output example.ir.json

MCP server

Run a local stdio MCP adapter for agent hosts:

archway mcp serve

The MCP host launches this command as a child process. It exposes capability discovery, service health, and Python translation tools backed by the same configured Archway Engine Service as the CLI. It does not listen on a port or contain the engine itself.

The process uses this machine's archway login sign-in and renews its tokens for as long as it runs; a host can instead pass ARCHWAY_CLIENT_ID/ARCHWAY_CLIENT_SECRET (or, for tests, ARCHWAY_TOKEN). Never put a credential in command arguments or commit it in a host configuration file.

Command output is JSON. Errors are written to standard error and do not include the configured bearer token.

The installed client also provides an offline reference for portable categorical IR:

archway ir guide
archway ir catalogue --output revision-21.catalogue.json
archway ir definitions classifier_spec
archway ir operations python.call
archway ir search "merge class"

These reference commands need neither a service nor a sign-in. They describe revision 21; for a document from an older engine, archway ir guide --revision N and archway ir schema --revision N give that revision's specification and JSON Schema (revisions 9 to 20).