Metadata-Version: 2.4
Name: unlegacy-cli
Version: 0.7.1
Summary: Unlegacy setup CLI for external coding agents
Author: Unlegacy
Project-URL: Homepage, https://app.unlegacy.ai
Project-URL: Repository, https://github.com/unlegacy-ai/unlegacy-core
Keywords: unlegacy,mcp,cli,coding-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# unlegacy-cli

Installable CLI for connecting local coding agents to Unlegacy MCP.

Unlegacy generates repository documentation, API references, knowledge graph
data, and Vault investigation docs in the platform. This CLI configures
external coding agents so they can consume that MCP surface.

## Install

Published package:

```sh
uv tool install unlegacy-cli
```

or:

```sh
pip install unlegacy-cli
```

After install, the command is saved on the user's machine as:

```sh
unlegacy --help
```

From a checkout:

```sh
pip install .
```

or:

```sh
uv tool install .
```

One-shot setup without preinstalling:

```sh
uv tool run --from 'unlegacy-cli>=0.7.1' unlegacy setup
```

## Distribution

Build the package artifacts:

```sh
uv build
```

Version 0.7.0 introduces device sign-in and project scope. Deploy the matching
backend and publish this version before distributing the frontend setup command.
For local verification before publication, use `uv run unlegacy setup` from this
checkout with `--project /path/to/project` and the local `--endpoint`.

The build creates `dist/unlegacy_cli-<version>.tar.gz` and
`dist/unlegacy_cli-<version>-py3-none-any.whl`. Publish those artifacts to the
Python package index used by Unlegacy clients.

## Setup

```sh
unlegacy setup
```

The interactive client picker supports Windows, macOS and Linux. Version 0.7.1
fixes the Windows `termios` import error; Windows users can use the same setup
command without extra flags. To refresh a cached one-shot installation:

```sh
uv tool run --refresh --from 'unlegacy-cli>=0.7.1' unlegacy setup
```

Keep any existing `--endpoint` option when upgrading a customer installation.

Run setup from your project folder. The wizard chooses **only this project**
by default, or **all projects for this user**, then lets you select clients.
The choice applies to both MCP configuration and the bundled skills.

On first setup, the CLI displays an eight-character code and opens the browser
at `/mcp?step=code`. Sign in, choose the organization and approve your code.
The terminal then installs the selected clients and runs doctor. Nothing is
approved merely by opening the page. Use `--no-browser` on a headless terminal.

The credential is saved privately in `~/.config/unlegacy/credentials.json`,
separately for each endpoint. Running setup in another project reuses that
connection after validating it; no new browser approval is needed. An expired
or revoked credential requires approval again. Use `--reconnect` to change the
connected organization. A network failure does not create another connection.
The production endpoint defaults to `https://app.unlegacy.ai/ai/mcp`.

```sh
# Configure the current project, or another folder, without repeating sign-in.
unlegacy setup --scope project --client claude-code --client codex
unlegacy setup --project /path/to/another-repository --client codex

# Explicitly make MCP and skills available in every project.
unlegacy setup --scope global --client claude-code --client codex

# Preview paths without authentication, network requests or writes.
unlegacy setup --project /path/to/repository --client all --dry-run

# Use this checkout's development server.
unlegacy setup --endpoint http://localhost:25250/ai/mcp
```

For automation, an existing credential can still be supplied with
`UNLEGACY_MCP_TOKEN` (or `--token`). The CLI never prints the token. HTTPS is
required except on loopback development hosts, and credential requests do not
follow redirects.

### Moving an existing global installation

Project setup detects global Unlegacy configuration and skills. The wizard asks
to migrate them; unattended setup requires `--remove-global`. Global entries are
removed only after project setup and doctor succeed. Other MCP servers and
unrelated skills are preserved; backups go under `~/.config/unlegacy/backups`.
Shared compatibility skill directories are included, so moving one may also
remove the global Unlegacy skill from another client that reads the same folder.
The wizard explains this before proceeding. Restart affected clients afterward.

```sh
unlegacy setup --scope project --client codex --remove-global
```

### Native installation locations

`PROJECT` means the enclosing Git repository root, or the specified/current
folder outside Git. `HOME` means your user profile. Client trust prompts still
apply; Codex loads project configuration only for trusted projects.

| Client | Project MCP | Global MCP | Project skills | Global skills |
| --- | --- | --- | --- | --- |
| Claude Code | Private project entry in `HOME/.claude.json` | `HOME/.claude.json` | `.claude/skills` | `HOME/.claude/skills` |
| Codex | `.codex/config.toml` | `HOME/.codex/config.toml` | `.agents/skills` | `HOME/.agents/skills` |
| Cursor | `.cursor/mcp.json` | `HOME/.cursor/mcp.json` | `.cursor/skills` | `HOME/.cursor/skills` |
| VS Code Copilot | `.vscode/mcp.json` | Default user profile `mcp.json` | `.github/skills` | `HOME/.copilot/skills` |
| OpenCode | `opencode.json` | `HOME/.config/opencode/opencode.json` | `.opencode/skills` | `HOME/.config/opencode/skills` |

The VS Code default user profile is `Library/Application Support/Code/User` on
macOS, `%APPDATA%/Code/User` on Windows and `.config/Code/User` on Linux.
Custom profiles, portable installs and custom client directory overrides are
not detected by this release. Scope controls where clients load Unlegacy; it
does not narrow the credential's organization/repository permissions.

Credential-bearing config files and backups use owner-only permissions on
POSIX. Project configs are added to Git's local `info/exclude`; setup refuses
tracked config files instead of inserting credentials into version control.
Untrack a personal config before setup, or keep a shared config and configure
credentials manually. Symlinked project targets outside the project are refused.
Packaged skills contain no credentials and may be versioned if desired.

Native behavior references: [Claude scopes](https://code.claude.com/docs/en/mcp),
[Codex configuration](https://developers.openai.com/codex/config-basic/),
[Codex skills](https://developers.openai.com/codex/skills/),
[Cursor skills](https://cursor.com/docs/skills),
[VS Code skills](https://code.visualstudio.com/docs/agent-customization/agent-skills),
and [OpenCode MCP](https://opencode.ai/docs/mcp-servers/).

Supported client values:

- `claude-code`
- `codex`
- `cursor`
- `vscode-copilot`
- `opencode`
- `all`

## Commands

```sh
unlegacy setup
unlegacy doctor
unlegacy install-skills --client codex
unlegacy status
```

## Bundled skill

`unlegacy setup` and `unlegacy install-skills` install one versioned skill bundle:

- `unlegacy` - authorized repository Knowledge and content retrieval

The bundle is self-contained; installing the external Superpowers plugin is not
required.

The skill is used only when you explicitly ask to consult Unlegacy: for example,
"ask Unlegacy about authentication", "pergunte ao legacy", "faça um legacy", or
`$unlegacy`. General code questions, mentions of legacy code, and work on the
Unlegacy project itself do not activate it. The request covers the current task
and its follow-ups, not unrelated later tasks. Codex also receives
`agents/openai.yaml` with implicit invocation disabled; use `$unlegacy` to
explicitly load the skill there. Natural-language selection depends on the
client's skill discovery behavior.

## Canonical MCP contract

The bundled skill targets Backend-authorized Catalog, Knowledge and content
reads. `list_repos`, `find_repos` and `repo_brief` resolve repository names and
availability. `search` and `org_survey` discover evidence in one
repository, a project or the organization. Survey coverage is the top 20
rank-fused hits, not an exhaustive inventory or confidence estimate.

`get_symbol` returns literal symbols and canonical entity refs. Pass those
complete refs to `symbol_context` and `impact`. File and docs tools use
canonical version IDs, paths, revisions and page cursors. No client constructs
object-store keys or sends physical graph identifiers.

Arbitrary `cypher` currently returns `CYPHER_NOT_SUPPORTED`; it does not call
KG. Vault-specific tools are not registered by this MCP server. `unlegacy
doctor` checks the repository tool inventory, not permissions or the full
runtime pipeline. Install this skill version with the matching server.

## Development

```sh
uv run pytest
```
