Metadata-Version: 2.4
Name: monarch-cloud
Version: 0.1.1
Summary: Public developer CLI for Monarch Cloud
Author: Africa Compute Fund
Project-URL: Homepage, https://app.africacomputefund.com
Project-URL: Documentation, https://app.africacomputefund.com/docs
Keywords: monarch,cloud,compute,developer-tools,cli
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.24

# Monarch Cloud CLI

A lightweight public developer client for the existing Monarch REST Platform API.

```bash
python -m pip install monarch-cloud
monarch login
monarch whoami
monarch catalog
monarch gpus
monarch models --scope catalog
monarch jobs
monarch wallet
monarch orgs
monarch projects
monarch init "My app" --blueprint backend
monarch status
monarch dev
monarch deploy hello ./hello.js
```

**Authentication:** `monarch login` prompts for an existing Monarch REST API key
without echoing it, validates it against `GET /v1/account/identity`, then saves
it in a mode-0600 file under your user configuration directory. For ephemeral
environments set `MONARCH_API_KEY` instead; this takes precedence. This is REST
API-key login, **not** the OAuth browser flow used by the MCP connector. Key
creation and account access are provided through Monarch Cloud.

`monarch mcp` prints the public OAuth MCP endpoint for compatible AI clients;
it does not bundle an MCP server or impersonate an OAuth token.

## Command surfaces

- Discovery: `catalog`, `gpus`, `models`, `datasets`, `jobs`, `job ID`,
  `wallet`, `inference-models`, `whoami`.
- Projects: `orgs`, `projects`, `init`, `use [PROJECT_ID]`, `status`, `dev`, `deploy NAME SOURCE_JS`.
- Migration: `migrate`, `migrate-storage`, `migrate-postgres`,
  `migrate-gcs`, `import-documents`.
- Account: `login`, `logout`, `mcp`.

`deploy` deploys one JavaScript **Project Function**, not arbitrary whole-app
infrastructure. Some public REST APIs and the MCP's purpose-built tools are
not yet wrapped as CLI commands; Cloud, REST and MCP remain the source of truth.

## Project ownership and Free-plan behavior

`monarch init "My app"` lists organizations internally and selects the sole
eligible one automatically. If multiple eligible organizations exist, an
interactive terminal displays names and asks which should own the new Project.
For automation, use `monarch init "My app" --org-id ORG_ID` (find IDs with
`monarch orgs`). The server always verifies admin privileges.

Each Free organization has a published hard limit on active Free Projects.
When the limit is reached, `init` offers to **select an existing Project**
instead of falsely claiming a new one was created. This selection is explicit
and produces `"created": false`; it does not purchase a plan or create a
second organization. For automation, inspect with `monarch projects` then
select an owned Project with `monarch use PROJECT_ID`.
Existing-Project selection deliberately removes any stale local server key:
it cannot recover another Project's one-time secret. `monarch status` and
`monarch dev` still work with the account API key.

Migration `--prepare` uses the same organization chooser but does not
substitute an existing Project for a new migration target.

Project selection is stored in `.monarch/project.json`. The one-time Project
server key is saved in `.monarch/server-key` and must never be committed.
Source migration secrets are only read from environment variables or named
credential files, not CLI arguments. The server enforces the same account,
scope, billing, quotas, and approvals as its other public clients.

## For maintainers

The public release is built from the **canonical** implementation at
`scripts/monarch_platform.py` using
`python scripts/package_monarch_cloud.py --build`. The staging tool copies
only this public module, the package metadata, and this README into an isolated
temporary build directory. The private `./monarch` operator CLI, admin scripts,
deployment infrastructure, and internal MCP server are not packaged.

There is no GitHub Actions publisher. The fixed-package, owner-confirmed
Monarch Operator MCP release operation can publish reviewed files through the
existing sovereign Estate when its scoped PyPI credential and build tools are
configured. It checks the exact source SHA and published artifact hashes.
Otherwise the owner can use the documented manual `uv publish` workflow.
See `docs/operations/MONARCH_CLOUD_PYPI.md` for release instructions.
