# mcloud-projects

Lists, inspects, and deletes Medusa Cloud projects, including their linked environments, to resolve project handles by name.

Skill by Medusa. Category: Shipping and ops.

## Install

Project (for this project only):

```sh
npx skills add medusajs/medusa-agent-skills --skill mcloud-projects
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add medusajs/medusa-agent-skills --skill mcloud-projects -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.
- Runs shell commands: Its steps run shell commands in your terminal.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 1215. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/medusajs/medusa-agent-skills/mcloud-projects)

## Source

[Open the source](https://github.com/medusajs/medusa-agent-skills/tree/HEAD/plugins/medusa-cloud/skills/mcloud-projects). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: mcloud-projects
description: Execute mcloud projects commands to list, get, or delete Cloud projects. Use when discovering projects, resolving project handles by name, or retrieving project details including linked environments.
allowed-tools: Bash(mcloud projects*), Bash(mcloud use*), Bash(jq*)
---

# Cloud CLI: Projects Commands

Execute `mcloud projects` commands to manage Cloud projects.

## Constraints

- `projects delete` is **irreversible** — removes all associated environments, deployments, and resources. Always confirm the project ID/handle before deleting.
- Use `--yes` with `delete` in non-interactive contexts (scripts, pipelines, agents).

## Commands

### projects list

List projects in an organization. If `--organization` is omitted (and no active context org is set), lists projects across all organizations you have access to, grouped by organization.

```bash
mcloud projects list --organization <org-id> --json
```

**Options:**
- `-o/--organization <id>` — Organization ID (falls back to active context; if unset, lists across all your organizations)
- `--json` — Output as JSON

### projects get

Retrieve a single project by its ID or handle.

```bash
mcloud projects get <project-id-or-handle> --organization <org-id> --json
```

**Arguments:**
- `project` — Project ID or handle (required)

**Options:**
- `-o/--organization <id>` — Organization ID (falls back to active context; **required**)
- `--json` — Output as JSON

### projects delete

Delete a project by its ID or handle. **Irreversible.**

```bash
mcloud projects delete <project-id-or-handle> \
  --organization <org-id> \
  --yes
```

**Arguments:**
- `project` — Project ID or handle (required)

**Options:**
- `-o/--organization <id>` — Organization ID (falls back to active context; **required**)
- `-y/--yes` — Skip confirmation prompt (required in non-interactive mode)
- `--json` — Output as JSON

## Project Fields (JSON)

| Field | Description |
|-------|-------------|
| `id` | Project ID |
| `handle` | URL-safe project handle (used in most commands) |
| `name` | Display name |
| `status` | `ready` when healthy |
| `region` | Deployment region (e.g. `us-east-1`) |
| `repository` | Linked GitHub repository (`owner/repo`) |
| `root_path` | Root path within the repository |
| `organization` | Owning organization (`id`, `name`, `created_at`) |
| `environments` | Array of associated environments (each may include `storefront_environments`) |

## Examples

```bash
# List all projects in an organization
mcloud projects list --organization org_123 --json

# Set context to a project by name
PROJECT_HANDLE=$(
  mcloud projects list --organization org_123 --json \
    | jq -r '.[] | select(.name == "My Store") | .handle'
)
mcloud use --project "$PROJECT_HANDLE"

# Get project details including environments
mcloud projects get my-store --organization org_123 --json

# List all environment handles for a project
mcloud projects get my-store --organization org_123 --json \
  | jq -r '.environments[].handle'

# Find project handle by name
mcloud projects list --organization org_123 --json \
  | jq -r '.[] | select(.name == "My Store") | .handle'

# Delete a project (irreversible — confirm before running)
mcloud projects delete old-project --organization org_123 --yes
```
````

- Previous: [mcloud-variables](https://syn4pse.dev/terminal/medusa-mcloud-variables.md)
- Next: [mcloud-logs](https://syn4pse.dev/terminal/medusa-mcloud-logs.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
