Archway

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

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 disables it in Archway (you must be signed in; it is refused within a minute) and forgets it here; its WorkOS registration can also be revoked in the WorkOS dashboard.

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 the service's default engine answers. 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

Each translation records the engine that produced it as engine_sha.

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 9. Translation also works with engines that produce revision 8, which is requested automatically when a selected engine offers nothing newer.

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 9 is the sole current contract. 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.