Metadata-Version: 2.5
Name: archway
Version: 0.16.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.

## 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](https://github.com/Archway-Labs-AI/Archway/blob/main/docs/contracts/portable-categorical-ir/migration-from-revision-9.md)
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:

```bash
uv tool install archway      # or: pipx install archway
```

## Signing in

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

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

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

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

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

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

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

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

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