Archway

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

0.16.1 release candidate

The client supports portable IR revisions 18 through 8, preferring 18. Engine selection defaults to the engine pinned by this CLI release: 9191b19154e68802a1322c0ec299349481fb18c8. Upgrading selects this engine unless you already set --engine or ARCHWAY_ENGINE. The hosted fallback remains unchanged for older clients. Revision-9 consumers must migrate their execution contracts and retranslate source, not merely update a JSON revision field. See the migration guide for operation changes, annotations, imports, merge classes and finalizer state.

This candidate is not yet a published release. Revision 18 adds module/class future-annotation namespace setup and preserves future-import runtime bindings. Type-parameter runtime semantics remain outside this release.

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

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. The Python transport API retains ArchwayClient(..., engine=None) for callers deliberately using a service default; pass DEFAULT_ENGINE_SHA from archway_client.client to adopt the CLI release target.

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 and advertises the preferred revision before publication. 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 the exact portable categorical IR revision it supports:

archway ir schema --output portable-ir.schema.json
archway ir guide
archway ir definitions wire_expr
archway ir operations python.call
archway ir search "merge class"

These reference commands need neither a service nor a sign-in. The bundled reference describes revision 12, including Python named-import reads. Translation also works with engines producing revision 11, 10, 9 or 8, choosing the newest mutually supported revision. Clients lacking revision 12 support must be upgraded before using an engine offering only revision 12.

What's new in 0.11.1

The client identifies itself with a User-Agent: archway/<version> header, as the default address requires. The previous default, Python's own, is refused there by an edge bot check.

What's new in 0.11.0

Engine selection (--engine / ARCHWAY_ENGINE), the engine_sha record, support for engines producing revision 8, and the default service address are new in this release.

Portable categorical IR revision 11 is the sole current contract. It adds an explicit python.imports@1.bind_star effect; readers must implement it or reject it explicitly. Python function definitions now require call_protocol (ordinary or async), preserving lazy coroutine creation after decoding, including bodies without await. An f-string replacement field is python.convert_value (only when !s, !r or !a is written) followed by python.format_value, which takes the value and its format spec as inputs. A dynamic spec such as {x:>{width}} is no longer lowered as calls to the program's global format, repr, str and ascii, so rebinding those names no longer changes an f-string's result. Revision 9 retains revision 8's class-scope declarations and revision 7's effectful Python protocol operations.

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 the exact portable categorical IR revision it supports:

archway ir schema --output portable-ir.schema.json
archway ir guide
archway ir definitions wire_expr
archway ir operations python.call
archway ir search "merge class"

These reference commands need neither a service nor a sign-in. The bundled revision-8 contract distinguishes class-body lexical captures from names explicitly declared global; historical revisions require a historical pinned client and service.

What's new in 0.10.0

Portable categorical IR revision 8 is the sole current contract. It makes Python class-scope declarations explicit by distinguishing lexical captures from names declared global. It retains revision 7's effectful Python protocol operations, faithful exception-handler dispatch, completion-flow correlations, and corrected augmented-assignment and ordered call-argument translation semantics.

archway translate example.py
archway ir guide

Use --ir-format python-serde only for a consumer that still requires the legacy Python-specific serialization.

Revisions 3 through 7 are not supported by this release. Historical consumers must use an Archway release pinned to the historical contract they require.