Metadata-Version: 2.5
Name: archway
Version: 0.11.1
Summary: Command-line client for Archway services
Project-URL: Homepage, https://archway-labs.ai
Author: Archway Labs
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: archway,cli,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: certifi>=2025.1.31
Requires-Dist: mcp<3,>=2
Description-Content-Type: text/markdown

# 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:

```bash
pipx install archway
```

## Configuration

Set your personal bearer token:

```bash
export ARCHWAY_TOKEN="<personal token>"
```

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:

```bash
archway --engine 27913a47 translate example.py
```

Each translation records the engine that produced it as `engine_sha`.

The health check does not require a token:

```bash
archway health
```

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

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

Translate one Python file:

```bash
archway translate example.py
```

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

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

## MCP server

Run a local stdio MCP adapter for agent hosts:

```bash
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:

```bash
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`.
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.

```bash
archway translate example.py
```

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

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

## MCP server

Run a local stdio MCP adapter for agent hosts:

```bash
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:

```bash
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`.
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.

```bash
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.
