MEGA CLI Reference#

The mega CLI is the shortest path for interactive Hub work and shell automation. Its command layout follows the same domain boundaries as the Web API and MegaHubClient.

Install#

Install the published Python package with one of these tools:

1uv tool install megatensors2pipx install megatensors3python -m pip install megatensors

Confirm the executable and environment:

1mega version2mega env3mega --help

Update an existing installation:

mega update

Authenticate#

1mega auth login2mega auth whoami

For automation, inject MEGA_TOKEN or pass --token to an individual command. See Authentication for device flow, stored tokens, scopes, and endpoint selection.

Browser login requests the scopes needed by the current CLI command surface: repo:read, repo:write, repo:delete, community:write, jobs:run, inference:run, mcp:use, account:keys, and webhooks:manage, plus the identity and refresh-token scopes. This CLI authorization is independent of the MCP Read/Write/Full preference. mega auth whoami shows the active token kind, role, and granted scopes so scripts can fail before attempting an unauthorized operation.

Trusted Publishers in GitHub Actions#

Organization and personal namespace owners can register a GitHub Actions Trusted Publisher. The workflow then exchanges GitHub's signed OIDC identity for a one-hour MEGA token; no long-lived MEGA_TOKEN secret is stored.

Set MEGA_OIDC_RESOURCE to the namespace handle, not a repository or Bucket ID. The same short-lived identity can publish repository revisions and mutable Bucket objects inside that namespace:

1permissions:2  contents: read3  id-token: write4 5steps:6  - uses: actions/checkout@v47  - run: python -m pip install megatensors8  - run: |9      mega buckets create model-team/release-artifacts --private --exist-ok10      mega buckets sync ./artifacts mega://buckets/model-team/release-artifacts11    env:12      MEGA_OIDC_RESOURCE: model-team

Trusted Publisher tokens have repository/Bucket read and publish access only. They cannot delete or move a Bucket, change its visibility, issue persistent S3 credentials, manage the account, or obtain a refresh token.

Command domains#

Repository workflows#

1mega repos create mega/demo --type model --exist-ok2mega upload mega/demo ./model --revision main3mega repos tag create mega/demo v1.0 --message "First release"4mega snapshot mega/demo --revision v1.0 --local-dir ./release5mega repos create mega/my-tools --type mcp6mega upload mega/my-tools ./README.md README.md --type mcp7mega cp ./plugin.json mega://mcps/mega/my-tools@main/plugin.json

Typed repository aliases expose the common operations without repeating --type:

1mega models list2mega datasets upload research/evals ./data3mega spaces list alice/demo --revision main

See Hub Repositories for file, revision, and community semantics.

MCP Marketplace workflows#

Search the public catalogue, inspect one listing, and install its optional local CLI, Skill, or Plugin companion:

1mega mcp search judge2mega mcp info mega/xpuoj --format json3mega mcp install mega/xpuoj

Files install under ~/.local/share/mega/mcp/<namespace>/<name> by default. The command requires a README, writes .mega-mcp.json, replaces atomically, and never executes publisher code. Use --revision, --dest, or --force when needed. AI clients still connect only to https://mega.tensorplay.cn/mcp.

Spaces workflows#

Create and publish an application repository under a personal or organization namespace:

1mega repos create mega/openapi --type space --public --exist-ok2mega spaces upload mega/openapi ./spaces/openapi . --sync \3  --commit-message "Publish OpenAPI explorer"4mega spaces info mega/openapi --format json5mega spaces restart mega/openapi6mega spaces wait mega/openapi --timeout 5m7mega spaces logs --follow mega/openapi

Runtime management is available directly from the CLI:

1mega spaces hardware2mega spaces runtime mega/openapi --format json3mega spaces settings mega/openapi --hardware cpu-upgrade4mega spaces variables add mega/openapi -e MODE=production5mega spaces secrets add mega/openapi -s API_TOKEN6mega spaces volumes set mega/openapi -v mega://datasets/mega/data:/datasets/data:ro7mega spaces dev-mode mega/openapi8mega spaces hot-reload mega/openapi app.py -f ./app.py9mega spaces pause mega/openapi

Use mega spaces templates, search, and card for discovery. Dev Mode keeps a writable source workspace, hot-reload atomically replaces one Python file without rebuilding the image, and ssh enters that same rootless container after Hub key and write-permission checks. Space volumes are read-only model, dataset, Space, or Bucket snapshots; use a Space storage tier for writable /data. Secret values are write-only and never appear in list output. The Spaces guide documents billing, Dev Mode entitlement, runtime states, and recovery.

Jobs workflows#

1mega jobs hardware2mega jobs balance3mega jobs run python:3.12-slim python -c 'print("hello")'4mega jobs ps --status RUNNING5mega jobs logs --follow --tail 100 <job-id>6mega jobs wait <job-id>7mega jobs usage

Recurring work lives under mega jobs scheduled. The Jobs guide documents every supported command, option, SDK method, and endpoint.

Sandbox workflows#

1mega sandbox create python:3.132mega sandbox exec <sandbox-id> -- python -V3mega sandbox spawn <sandbox-id> -- python -m http.server 80004mega sandbox process ls <sandbox-id>5mega sandbox cp ./input.json <sandbox-id>:/workspace/input.json6mega sandbox kill <sandbox-id>

Dedicated sessions use the authenticated native Sandbox API. Read-only model, dataset, and Space snapshots can be attached with repeatable -v/--volume mounts; bucket and writable mounts are rejected. File transfer uses bounded chunks, and background processes can be inspected and stopped by PID.

mega sandbox pool create maintains a reusable template for faster Session startup. Pool capacity and placement are managed by the service and may vary with account limits and current availability.

Extensions and skills#

1mega extensions search2mega extensions install ohtensorplay/mega-example3mega example --help4mega extensions update5 6mega skills preview7mega skills list8mega skills add9mega skills update

Extensions execute third-party code, so install only sources you trust. mega skills add installs the generated mega-cli skill by default; named skills come from the synchronized public MEGA skills marketplace.

Webhook workflows#

1mega webhooks create \2  --name release-verifier \3  --url https://ci.example/hooks/mega \4  --event repo.updated5 6mega webhooks test <webhook-id>7mega webhooks deliveries <webhook-id> --limit 50

The create command reveals a generated signing secret once. See Webhooks before configuring a production receiver.

Git, SSH, and GPG smoke test#

MEGA publishes Web/API URLs on mega.tensorplay.cn, HTTPS Git directly on git.tensorplay.cn, and SSH Git on the DNS-only ssh.tensorplay.cn host. Existing Hub-host Git remotes continue to redirect to the HTTPS Git data plane.

1ssh-keygen -t ed25519 -C "$USER@$(hostname)" -f ~/.ssh/id_ed25519_mega2mega auth keys add ~/.ssh/id_ed25519_mega.pub --name workstation3curl -sSfL https://mega.tensorplay.cn/git-xet/install.sh | sh4git clone https://git.tensorplay.cn/OWNER/REPOSITORY.git5ssh -T -i ~/.ssh/id_ed25519_mega git@ssh.tensorplay.cn6git clone git@ssh.tensorplay.cn:OWNER/REPOSITORY

Register and exercise a signing key whose email matches the MEGA account:

1gpg --armor --export ACCOUNT_EMAIL > mega-signing-key.asc2mega auth keys add mega-signing-key.asc --type gpg --name release3git config user.email ACCOUNT_EMAIL4git config user.signingkey "$(gpg --list-secret-keys --with-colons ACCOUNT_EMAIL | awk -F: '$1=="sec" {print $5; exit}')"5git config commit.gpgsign true6git commit --allow-empty -m "Verify signed push"7git push origin HEAD8mega repos history OWNER/REPOSITORY --format json

The history record reports signature_status and signer_fingerprint. See Authentication for host configuration and identity rules.

Structured output#

Commands that return records support shared formatting options:

Prefer JSON for scripts:

1mega repos list --owner research --format json2mega jobs ps --status RUNNING --format json

Use quiet output for shell composition:

mega repos list --type model -q

Shell completion and help#

1mega --show-completion2mega --install-completion3mega repos create --help4mega jobs scheduled run --help

Leaf-command help is the authoritative option contract for the installed version.

Environment variables#

Automation rules#

• Use --format json instead of parsing human tables.
• Pass --yes only when the target ID was validated earlier in the same workflow.
• Inject secrets with environment variables; do not place tokens directly in committed scripts.
• Pin repository automation to an explicit branch, tag, or commit.
• Check the exit code. Foreground mega jobs run and mega jobs wait fail when the Job does not complete successfully.