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:

pipx install archway

Configuration

Set the service URL and personal bearer token:

export ARCHWAY_URL="https://your-archway-service.example.com"
export ARCHWAY_TOKEN="<personal token>"

The health check does not require a token:

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 host must provide ARCHWAY_URL and ARCHWAY_TOKEN to the process. Do not put the token 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 do not require ARCHWAY_URL or ARCHWAY_TOKEN.

What's new in 0.6.0

Version 0.6.0 makes portable categorical IR revision 5 the current default. Revision 5 preserves revisions 3 and 4 as explicitly selectable compatibility formats and adds explicit control-continuation correlation for completion flow. It also ships the translation contract used by the current engine after the completion, augmented-assignment, and ordered-call-argument corrections.

archway translate example.py --ir-format portable
archway ir guide

Use --portable-revision 3 or --portable-revision 4 (and the corresponding archway ir ... --revision option) only when integrating an older consumer.

What's new in 0.5.0

Version 0.5.0 adds the portable categorical IR revision-4 reference alongside revision 3. Revision 4 makes classified routing and completion behavior explicit, including pattern classifiers, iterator outcomes, exception classifiers, finalizer completion, and loop fallthrough. Offline reference commands accept --revision 4 so clients can inspect the exact schema and semantic guide used by updated Archway Engine services.

Request revision 4 explicitly when translating:

archway translate example.py --ir-format portable --portable-revision 4

The local MCP adapter also preserves bounded, credential-safe Archway client errors as inspectable tool errors across supported MCP 2.x releases.

What's new in 0.4.0

Version 0.4.0 adds the offline archway ir reference surface. It packages the portable categorical IR revision-3 JSON Schema and semantic guide, supports exact definition and operation lookup, and provides deterministic search over both artifacts. Translation behavior and service configuration are unchanged.