# m2-market CLI contract v1

The CLI is the only marketplace surface that calls m2-ledger directly. Store, Scout, and Hermes
consume the CLI JSON contract.

Config: `~/.m2-market/config.toml` mode `0600`.

Required keys: `operator_id`, `tenant`, `ledger_url`, `ledger_api_key`, `memory_api_url`,
`memory_api_key`, `forgejo_url`, `forgejo_token`, `apply_adapter`.

State: `~/.m2-market/state.json`. Install entries MUST store `grant_id` and `tx_group_id`.

## Verbs

- `m2-market search <query> [--type solution|capability|resource|service] [--limit N] [--json]`
- `m2-market show <listing_id> [--json]`
- `m2-market install <listing_id> [--yes] [--json]`
- `m2-market uninstall <listing_id> [--yes] [--json]`
- `m2-market upgrade <listing_id> [--to <semver>] [--yes] [--json]`
- `m2-market wallet [--operator <operator_id>] [--json]`
- `m2-market publish <bundle-dir> [--tenant-visibility <tenant-or-*>]`
- `m2-market package init|import-fedlearn|validate|build|diff-permissions|evidence-summary|verify-release`
- `m2-market reindex`
- `m2-market propose "<intent>" --tenant <tenant> --operator <operator_id> --json`
- `m2-market evidence capture|submit|show`
- `m2-market telemetry submit <event-jsonl>`

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success, including idempotent no-op install. |
| 1 | Usage error, unsupported operation, or direct install refused for `price.model=job`. |
| 2 | Listing, release, license, or local install state not found. |
| 3 | Insufficient funds or ledger payment declined before apply. |
| 4 | Apply, verify, uninstall, or upgrade failed after settlement; CLI attempted refund when applicable. |
| 5 | Schema validation, tenant firewall, secret scan, permissions, or publish gate rejection. |
| 6 | External dependency unavailable or deferred adapter path not landed. |

## `show --json`

The detail payload is frozen for Store and Scout:

```json
{
  "schema_version": "m2.market.show.v1",
  "listing": {
    "schema_version": "m2.listing.v1",
    "listing_id": "lst_mm-pdf-report",
    "solution_id": "sol_mm-pdf-report",
    "solution_version": "1.0.0",
    "inventory_type": "solution",
    "name": "MM PDF Report",
    "summary": "Generate branded PDF reports.",
    "category": "reporting",
    "price": {"model": "fixed", "amount": 25, "currency": "m2cr"},
    "seller": {"operator_id": "op_m2core", "display_name": "M2 Core"},
    "content_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "tenant_visibility": ["*"],
    "status": "published",
    "install_ref": "lst_mm-pdf-report-v1.0.0"
  },
  "solution": {
    "schema_version": "m2.solution.v1",
    "solution_id": "sol_mm-pdf-report",
    "name": "MM PDF Report",
    "summary": "Generate branded PDF reports.",
    "intent": "Turn approved analysis into a styled client-ready PDF report.",
    "deployment": {
      "recipe_ref": "recipe.yaml",
      "entrypoint": "mm-pdf generate <input.md>",
      "verify_command": "mm-pdf --version"
    },
    "applicability": {
      "image_classes": ["primus", "agent-latest"],
      "roles": ["operator"],
      "tool_requirements": ["bash"]
    },
    "tenant_scope": "m2-core",
    "evidence": [{"source": "forgejo:m2/m2-market/listings/lst_mm-pdf-report/evidence/provenance.jsonl"}],
    "content_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "price": {"model": "fixed", "amount": 25, "currency": "m2cr"},
    "seller": {"operator_id": "op_m2core", "display_name": "M2 Core"},
    "license": {
      "license_id": "lic_m2_market_standard_v1",
      "terms": "m2-market-standard-v1",
      "scope": "operator",
      "major_version_coverage": true,
      "allows_internal_modification": true,
      "allows_redistribution": false,
      "support": "best_effort"
    }
  },
  "wallet": {"operator_id": "op_chris", "balance": 100, "currency": "m2cr", "as_of": "2026-07-02T00:00:00Z"},
  "install_state": {
    "status": "not_installed",
    "installed_version": null,
    "grant_id": null,
    "tx_group_id": null
  },
  "permissions_diff": {
    "schema_version": "m2.permissions_diff.v1",
    "mode": "new_install",
    "listing_id": "lst_mm-pdf-report",
    "current_install_ref": null,
    "target_install_ref": "lst_mm-pdf-report-v1.0.0",
    "summary": {"added": 2, "removed": 0, "changed": 0, "unchanged": 0, "risk": "medium"},
    "items": [
      {
        "permission_id": "fs-write-agent-home",
        "action": "added",
        "kind": "filesystem",
        "access": "write",
        "scope": "${AGENT_HOME}/.claude/skills/mm-pdf",
        "target": "skill files",
        "reason": "install skill files",
        "risk": "low",
        "requires_confirmation": false
      }
    ]
  }
}
```

`permissions_diff.mode` is one of `new_install`, `upgrade`, `reinstall`, `uninstall`, or
`no_change`. `items[].action` is one of `added`, `removed`, `changed`, or `unchanged`.