Metadata-Version: 2.4
Name: mirrorcommons
Version: 0.5.3
Summary: CLI for Mirror Commons: create continuity manifests for external AI artifacts and publish reviewed community mirrors.
Author: Mirror Commons
License-Expression: MIT
Project-URL: Homepage, https://mirrorcommons.com
Project-URL: Source, https://github.com/Hashem-Al-Qurashi/mirrorcommons-cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: huggingface_hub>=0.30
Requires-Dist: cryptography>=43
Provides-Extra: s3
Requires-Dist: boto3>=1.35; extra == "s3"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# Mirror Commons CLI

The `mirrorcommons` command is the web site's command-line companion. It lets people discover and download public releases, publish complete model repositories, and produce private continuity evidence without executing model code.

`artifactgrid` remains as a compatibility alias for existing scripts during the v1 migration.

## Install and sign in

```bash
cd cli
python3 -m pip install -e .
mirrorcommons auth login
mirrorcommons auth status
```

Login uses a short-lived browser approval. The CLI stores only the resulting scoped session in the current user's private configuration directory. For automation, set `MIRRORCOMMONS_TOKEN` instead.

## Discover and download

```bash
mirrorcommons models list --query qwen
mirrorcommons models info qwen3-8-27b
mirrorcommons models files qwen3-8-27b
mirrorcommons models versions qwen3-8-27b

mirrorcommons models download qwen3-8-27b --output ./qwen
mirrorcommons models download qwen3-8-27b \
  --version <version-id> \
  --include '*.json' \
  --exclude '*tokenizer*' \
  --output ./selected-files
```

Downloads are manifest-driven. Every file is fetched through a short-lived authorization and verified against the published SHA-256 digest. The downloaded directory includes a lockfile identifying the exact public version.

## Publish a complete mirror

Mirror Commons creates a **complete opaque copy** of ordinary repository files. It preserves filenames and bytes without importing or executing model code. Symlinks, traversal paths, VCS internals, caches, and transient files are rejected.

For a public Hugging Face source, the remote workflow transfers from Hugging Face to staging infrastructure; your home connection does not carry the model bytes:

```bash
mirrorcommons auth login
mirrorcommons publish from-hf \
  https://huggingface.co/acme/model \
  --slug acme-model \
  --display-name 'Acme Model' \
  --license apache-2.0 \
  --remote \
  --yes
```

Local multipart publishing is also available:

```bash
mirrorcommons publish create \
  --slug acme-model \
  --display-name 'Acme Model' \
  --declared-license apache-2.0 \
  --origin source_mirror \
  --source-url https://huggingface.co/acme/model \
  --revision <artifact-commit>

mirrorcommons publish source-challenge --draft <mirror-id>
mirrorcommons publish verify-source \
  --draft <mirror-id> \
  --proof-revision <commit-containing-controller-proof>

mirrorcommons publish inspect \
  --snapshot-dir ./model \
  --slug acme-model \
  --origin source_mirror \
  --source-control official_source_controller_verified \
  --source-url https://huggingface.co/acme/model \
  --revision <artifact-commit> \
  --output ./mirror-manifest.json

mirrorcommons publish upload \
  --draft <mirror-id> \
  --manifest ./mirror-manifest.json \
  --snapshot-dir ./model
```

The proof revision is separate from the immutable artifact revision. A community mirror never claims repository control. Every submission remains private until review.

## Continuity evidence

The local-first continuity commands work with an exact public Hugging Face revision and customer-controlled storage:

```bash
mirrorcommons continuity inspect --source-url <url> --revision <commit> --download
mirrorcommons continuity source-check --source-url <url> --revision <commit> --output source.json
mirrorcommons continuity protect --source-url <url> --revision <commit> --download --backup-dir ./backup
mirrorcommons continuity verify --manifest ./backup/artifactgrid-manifest.json --backup-dir ./backup
mirrorcommons continuity restore --manifest ./backup/artifactgrid-manifest.json --backup-dir ./backup --restore-dir ./restore
mirrorcommons continuity report --manifest ./backup/artifactgrid-manifest.json --backup-dir ./backup --output report.html
```

Install S3/R2 support with `python3 -m pip install -e '.[s3]'`. Credentials remain in the customer's standard local AWS credential chain and are never sent to Mirror Commons.

## Production AI Continuity Audit

Paid audit customers can create a private evidence package for up to ten public Hugging Face dependencies:

```bash
mirrorcommons audit run \
  --input ./examples/continuity-audit.json \
  --output ./continuity-report
```

The runner creates `audit-evidence.json`, `continuity-report.html`, and `audit-manifest.json`. It reports factual states such as verified, self-reported, not evidenced, and not performed; it does not provide legal clearance or malware certification.

See [the founder delivery guide](../docs/production-ai-continuity-audit.md) for the private service workflow.

## Compatibility

Existing flat commands and the `artifactgrid` executable continue to work in v1. New documentation uses grouped `mirrorcommons` commands.
