npm package: @framemesh/cli
Description: CLI for the Framemesh cloud platform
Latest version: 0.3.0

# @framemesh/cli

Command-line interface for the [Framemesh](https://framemesh.cloud) cloud platform. Manage VMs, databases, storage, apps, streaming, networking, and billing directly from your terminal.

Built on top of [`@framemesh/sdk`](../sdk).

## Installation

```bash
npm install -g @framemesh/cli
```

Requires Node.js >= 20. After installation, the `fmesh` command is available globally.

## Quick Start

```bash
# 1. Authenticate
fmesh login

# 2. Set defaults so you don't need --org and --project on every command
fmesh config set default-org my-org
fmesh config set default-project my-project

# 3. Use it
fmesh compute vms list
fmesh databases list
fmesh apps list
```

## Authentication

### Interactive login

```bash
fmesh login
```

Prompts for your API key, validates it against the API, and stores it in `~/.framemesh/credentials.json` (file permissions: `0600`).

### Environment variable

Set `FRAMEMESH_API_KEY` to skip interactive login:

```bash
export FRAMEMESH_API_KEY=fm_your_api_key
fmesh compute vms list
```

The environment variable takes precedence over stored credentials.

### Logout

```bash
fmesh logout
```

Removes stored credentials.

## Configuration

Configuration is stored in `~/.framemesh/`:

| File | Purpose |
|------|---------|
| `config.json` | Default org, project, API URL |
| `credentials.json` | API key (mode `0600`) |

### Config commands

```bash
# Set a value
fmesh config set default-org my-org
fmesh config set default-project my-project
fmesh config set api-url https://api.framemesh.cloud/api/v1

# Get a value
fmesh config get default-org

# List all config
fmesh config list
```

### Available config keys

| Key | Description |
|-----|-------------|
| `default-org` | Default organization slug. |
| `default-project` | Default project slug. |
| `api-url` | API base URL (default: `https://api.framemesh.cloud/api/v1`). |

## Global Options

These options can be added to any command:

| Option | Description |
|--------|-------------|
| `--org <slug>` | Organization slug (overrides `default-org`). |
| `--project <slug>` | Project slug (overrides `default-project`). |
| `--output <format>` | Output format: `table` (default), `json`, `yaml`. |
| `--api-url <url>` | API URL (overrides config and env). |

Example:

```bash
fmesh compute vms list --org other-org --project staging --output json
```

## Output Formats

### Table (default)

```
ID                                    NAME    STATUS   FLAVOR      IMAGE         CREATED
a1b2c3d4-e5f6-7890-abcd-ef1234567890  web-1   active   c1.medium   ubuntu-24.04  3/15/2026
```

### JSON

```bash
fmesh compute vms list --output json
```

```json
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "web-1",
    "status": "active"
  }
]
```

### YAML

```bash
fmesh compute vms list --output yaml
```

```yaml
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: web-1
status: active
---
```

## Commands Reference

### Authentication

```bash
fmesh login                          # Authenticate with API key
fmesh logout                         # Remove stored credentials
```

### Configuration

```bash
fmesh config set <key> <value>       # Set a config value
fmesh config get <key>               # Get a config value
fmesh config list                    # Show all config values
```

---

### Organizations

```bash
fmesh orgs list                      # List organizations
fmesh orgs get <slug>                # Get an organization
fmesh orgs create --name <name> [--description <desc>]
                                     # Create an organization
fmesh orgs delete <slug>             # Delete an organization
```

Examples:

```bash
fmesh orgs list
fmesh orgs create --name "Acme Corp"
fmesh orgs get acme-corp
fmesh orgs delete acme-corp
```

---

### Projects

Requires `--org` or `default-org` to be set.

```bash
fmesh projects list                  # List projects
fmesh projects get <slug>            # Get a project
fmesh projects create --name <name> [--description <desc>]
                                     # Create a project
fmesh projects delete <slug>         # Delete a project
```

Examples:

```bash
fmesh projects list --org acme-corp
fmesh projects create --name "Production"
fmesh projects get production
```

---

### Compute

Requires `--org`/`--project` or defaults to be set.

#### Virtual Machines

```bash
fmesh compute vms list               # List VMs
fmesh compute vms get <id>           # Get a VM
fmesh compute vms create             # Create a VM
    --name <name>                    #   VM name (required)
    --flavor <id>                    #   Flavor ID (required)
    --image <id>                     #   Image ID (required)
    [--network <ids...>]             #   Network IDs
    [--security-group <ids...>]      #   Security group IDs
    [--ssh-key <ids...>]             #   SSH key IDs
    [--volume-size <gb>]             #   Root volume size in GB
fmesh compute vms delete <id>        # Delete a VM
fmesh compute vms action <id>        # Perform VM action
    --action <action>                #   start, stop, or reboot
```

Examples:

```bash
fmesh compute vms list
fmesh compute vms create --name web-1 --flavor c1.medium --image ubuntu-24.04 \
  --network net-1 --security-group sg-default --ssh-key my-key
fmesh compute vms action abc123 --action stop
fmesh compute vms delete abc123
```

---

### Databases

Requires `--org`/`--project` or defaults to be set.

```bash
fmesh databases list                 # List databases
fmesh databases get <id>             # Get a database
fmesh databases create               # Create a database
    --name <name>                    #   Database name (required)
    --engine <engine>                #   postgresql, mysql, mongodb, redis (required)
    [--version <version>]            #   Engine version (default: latest)
    [--plan <plan>]                  #   Plan ID (default: small)
fmesh databases delete <id>          # Delete a database
fmesh databases connection <id>      # Get connection info
```

Examples:

```bash
fmesh databases list
fmesh databases create --name main-db --engine postgresql --version 16 --plan medium
fmesh databases connection abc123
fmesh databases delete abc123
```

---

### Storage

Requires `--org`/`--project` or defaults to be set.

#### Volumes

```bash
fmesh storage volumes list           # List volumes
fmesh storage volumes get <id>       # Get a volume
fmesh storage volumes create         # Create a volume
    --name <name>                    #   Volume name (required)
    --size <gb>                      #   Size in GB (required)
    [--storage-class <class>]        #   Storage class
    [--encrypted]                    #   Enable encryption
fmesh storage volumes delete <id>    # Delete a volume
```

#### Buckets

```bash
fmesh storage buckets list           # List buckets
fmesh storage buckets get <id>       # Get a bucket
fmesh storage buckets create         # Create a bucket
    --name <name>                    #   Bucket name (required)
    [--versioning]                   #   Enable versioning
    [--region <region>]              #   Region
fmesh storage buckets delete <id>    # Delete a bucket
```

Examples:

```bash
fmesh storage volumes create --name data-vol --size 100 --encrypted
fmesh storage buckets create --name assets --versioning
fmesh storage volumes list --output json
```

---

### Apps (PaaS)

Requires `--org`/`--project` or defaults to be set.

```bash
fmesh apps list                      # List apps
fmesh apps get <id>                  # Get an app
fmesh apps create                    # Create an app
    --name <name>                    #   App name (required)
    [--description <desc>]           #   Description
    [--port <port>]                  #   Port number
fmesh apps delete <id>               # Delete an app
fmesh apps deploy <id>               # Trigger deployment
    [--branch <branch>]              #   Branch to deploy
```

Examples:

```bash
fmesh apps create --name my-api --port 8080
fmesh apps deploy abc123 --branch main
fmesh apps list --output json
```

---

### Streaming

Requires `--org`/`--project` or defaults to be set.

```bash
fmesh streaming streams list         # List streams
fmesh streaming streams get <id>     # Get a stream
fmesh streaming streams create       # Create a stream
    --name <name>                    #   Stream name (required)
    [--auth-mode <mode>]             #   open, ingest_only, egress_only, all, disabled
    [--record]                       #   Enable recording
fmesh streaming streams delete <id>  # Delete a stream
```

Examples:

```bash
fmesh streaming streams create --name live-event --auth-mode ingest_only --record
fmesh streaming streams list
```

---

### Network

Requires `--org`/`--project` or defaults to be set.

#### Networks

```bash
fmesh network networks list          # List private networks
```

#### Floating IPs

```bash
fmesh network floating-ips list      # List floating IPs
```

#### Security Groups

```bash
fmesh network security-groups list   # List security groups
```

Examples:

```bash
fmesh network networks list
fmesh network floating-ips list --output json
fmesh network security-groups list
```

---

### Billing

Requires `--org` or `default-org` to be set.

```bash
fmesh billing invoices list          # List invoices
```

Example:

```bash
fmesh billing invoices list --org acme-corp
fmesh billing invoices list --output json
```

---

### API Keys

```bash
fmesh api-keys list                  # List API keys (coming soon)
fmesh api-keys create --name <name>  # Create an API key (coming soon)
fmesh api-keys delete <id>           # Delete an API key (coming soon)
```

API key management commands are planned but not yet implemented.

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `FRAMEMESH_API_KEY` | API key. Overrides stored credentials from `fmesh login`. |
| `FRAMEMESH_API_URL` | API base URL. Overrides the config file value. |

## Scripting

The CLI is designed to work well in scripts. Use `--output json` for machine-readable output:

```bash
# Get all VM IDs as a JSON array
fmesh compute vms list --output json | jq '.[].id'

# Create a VM and capture the ID
VM_ID=$(fmesh compute vms create --name web-1 --flavor c1.medium \
  --image ubuntu-24.04 --output json | jq -r '.id')

# Use in a loop
for id in $(fmesh databases list --output json | jq -r '.[].id'); do
  fmesh databases connection "$id" --output json
done
```

## License

MIT