MosisService/portal/internal/web/docs/cli.md

# CLI Reference

The Mosis CLI (`mosis`) is a command-line tool for building, testing, and publishing Mosis apps.

## Installation

### Windows

Download the installer from your [Developer Dashboard](/dashboard) or use:

```powershell
# Using winget
winget install omixlab.mosis-cli

# Or download directly
curl -o mosis-cli.exe https://dl.omixlab.com/cli/windows/mosis.exe
```

### macOS

```bash
# Using Homebrew
brew install omixlab/tap/mosis-cli

# Or download directly
curl -fsSL https://dl.omixlab.com/cli/macos/mosis > /usr/local/bin/mosis
chmod +x /usr/local/bin/mosis
```

### Linux

```bash
# Download binary
curl -fsSL https://dl.omixlab.com/cli/linux/mosis > ~/.local/bin/mosis
chmod +x ~/.local/bin/mosis

# Or using snap
sudo snap install mosis-cli
```

## Quick Start

```bash
# Create a new project
mosis init myapp

# Build the package
cd myapp
mosis build

# Test locally
mosis run

# Login and publish
mosis login
mosis publish
```

## Commands

### mosis init

Create a new Mosis app project.

```bash
mosis init <name> [options]
```

**Arguments:**
- `name` - Project name (creates directory)

**Options:**
| Option | Description |
|--------|-------------|
| `--template <name>` | Use a starter template |
| `--package-id <id>` | Set package ID |
| `--no-git` | Don't initialize git repo |

**Templates:**
- `default` - Basic app structure
- `minimal` - Bare minimum files
- `navigation` - Multi-screen with navigation
- `form` - Form handling example
- `list` - Scrollable list example

**Example:**
```bash
mosis init myapp --template navigation --package-id com.example.myapp
```

**Output:**
```
myapp/
├── manifest.json
├── icon.png
├── assets/
│   ├── main.rml
│   └── styles.rcss
└── .mosis/
    └── config.json
```

---

### mosis build

Build a `.mosis` package from your project.

```bash
mosis build [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `-o, --output <path>` | Output file path |
| `--no-sign` | Skip signing (dev only) |
| `--verbose` | Show detailed output |
| `--validate-only` | Validate without building |

**Example:**
```bash
mosis build -o dist/myapp.mosis
```

**Build Process:**
1. Validates manifest.json
2. Checks all referenced files exist
3. Validates RML/RCSS syntax
4. Creates compressed package
5. Signs with developer key (if available)

---

### mosis validate

Validate your project without building.

```bash
mosis validate [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--strict` | Enable strict validation |
| `--fix` | Auto-fix simple issues |

**Checks performed:**
- Manifest schema validation
- Required files existence
- Icon sizes and formats
- RML/RCSS syntax
- Lua syntax
- Package size limits

**Example output:**
```
✓ manifest.json is valid
✓ All required icons present
✓ Entry point exists: assets/main.rml
✓ RML syntax valid (3 files)
✓ RCSS syntax valid (2 files)
✓ Lua syntax valid (1 file)
✓ Package size: 45KB (under 10MB limit)

Validation passed!
```

---

### mosis run

Run your app in the local designer for testing.

```bash
mosis run [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--device <name>` | Target device profile |
| `--scale <factor>` | Window scale factor |
| `--hot-reload` | Enable hot reload (default) |
| `--no-hot-reload` | Disable hot reload |

**Device profiles:**
- `phone` - Standard phone (1080x1920)
- `tablet` - Tablet (1200x1920)
- `watch` - Watch (360x360)

**Example:**
```bash
mosis run --device phone --scale 0.5
```

---

### mosis login

Authenticate with the developer portal.

```bash
mosis login [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--token <token>` | Use API token directly |
| `--browser` | Open browser for OAuth |

**Interactive login:**
```bash
$ mosis login
Opening browser for authentication...
✓ Logged in as developer@example.com
```

**Token login (for CI/CD):**
```bash
mosis login --token YOUR_API_TOKEN
```

---

### mosis logout

Log out of the developer portal.

```bash
mosis logout
```

---

### mosis publish

Upload and submit your app for review.

```bash
mosis publish [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--notes <text>` | Release notes |
| `--notes-file <path>` | Release notes from file |
| `--draft` | Upload as draft (don't submit) |
| `--track <name>` | Release track (production/beta) |

**Example:**
```bash
mosis publish --notes "Bug fixes and performance improvements"
```

**Process:**
1. Builds package (if needed)
2. Uploads to portal
3. Runs automated validation
4. Submits for review (unless `--draft`)

---

### mosis status

Check the status of your app submissions.

```bash
mosis status [app-id]
```

**Example output:**
```
com.example.myapp

Latest Version: 1.2.0 (code: 5)
Status: In Review
Submitted: 2 hours ago

Previous Versions:
  1.1.0 (4) - Published
  1.0.0 (1) - Published
```

---

### mosis keys

Manage signing keys.

```bash
mosis keys <subcommand>
```

**Subcommands:**

#### keys generate

Generate a new signing keypair.

```bash
mosis keys generate [options]
```

| Option | Description |
|--------|-------------|
| `-o, --output <path>` | Output directory |
| `--name <name>` | Key name |

```bash
$ mosis keys generate --name production
Generated keypair:
  Private: ~/.mosis/keys/production.key
  Public:  ~/.mosis/keys/production.pub

Keep your private key secure! Never share it.
```

#### keys register

Upload your public key to the portal.

```bash
mosis keys register <key-file>
```

```bash
$ mosis keys register ~/.mosis/keys/production.pub
✓ Key registered successfully
  Key ID: k_abc123xyz
  Algorithm: Ed25519
```

#### keys list

List registered keys.

```bash
$ mosis keys list
ID           Name        Created     Status
k_abc123xyz  production  2024-01-15  Active
k_def456uvw  development 2024-01-10  Active
```

#### keys revoke

Revoke a registered key.

```bash
mosis keys revoke <key-id>
```

---

### mosis config

Manage CLI configuration.

```bash
mosis config <subcommand>
```

**Subcommands:**

#### config get

Get a configuration value.

```bash
mosis config get <key>
```

#### config set

Set a configuration value.

```bash
mosis config set <key> <value>
```

#### config list

List all configuration.

```bash
$ mosis config list
api_url = https://api.omixlab.com
designer_path = /usr/local/bin/mosis-designer
default_key = production
```

**Configuration keys:**
| Key | Description | Default |
|-----|-------------|---------|
| `api_url` | API endpoint | https://api.omixlab.com |
| `designer_path` | Path to designer | (auto-detected) |
| `default_key` | Default signing key | (none) |
| `auto_build` | Build before publish | true |

---

### mosis doctor

Diagnose common issues with your setup.

```bash
$ mosis doctor
Checking Mosis CLI installation...

✓ CLI version: 1.2.0
✓ Designer found: /usr/local/bin/mosis-designer
✓ Authenticated as: developer@example.com
✓ Signing key configured: production
✓ Network connectivity OK

All checks passed!
```

---

### mosis version

Show CLI version information.

```bash
$ mosis version
mosis-cli version 1.2.0
Built: 2024-01-15
Go: 1.21.5
```

---

### mosis help

Show help for any command.

```bash
mosis help [command]
mosis <command> --help
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `MOSIS_API_URL` | Override API endpoint |
| `MOSIS_TOKEN` | API token for authentication |
| `MOSIS_KEY_PATH` | Path to signing key |
| `MOSIS_NO_COLOR` | Disable colored output |
| `MOSIS_DEBUG` | Enable debug logging |

## Configuration Files

### Global Config

Location: `~/.mosis/config.json`

```json
{
  "api_url": "https://api.omixlab.com",
  "default_key": "production",
  "auto_build": true
}
```

### Project Config

Location: `.mosis/config.json` (in project root)

```json
{
  "signing_key": "production",
  "build_output": "dist/"
}
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Authentication required |
| 4 | Validation failed |
| 5 | Network error |
| 6 | Build failed |

## CI/CD Integration

### GitHub Actions

```yaml
name: Publish Mosis App
on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Mosis CLI
        run: |
          curl -fsSL https://dl.omixlab.com/cli/linux/mosis > mosis
          chmod +x mosis
          sudo mv mosis /usr/local/bin/

      - name: Build and Publish
        env:
          MOSIS_TOKEN: ${{ secrets.MOSIS_TOKEN }}
        run: |
          mosis build
          mosis publish --notes "Release ${GITHUB_REF#refs/tags/}"
```

### GitLab CI

```yaml
publish:
  image: ubuntu:latest
  script:
    - curl -fsSL https://dl.omixlab.com/cli/linux/mosis > /usr/local/bin/mosis
    - chmod +x /usr/local/bin/mosis
    - mosis build
    - mosis publish --notes "Release $CI_COMMIT_TAG"
  only:
    - tags
  variables:
    MOSIS_TOKEN: $MOSIS_TOKEN
```

## Troubleshooting

### "Command not found"

Ensure the CLI is in your PATH:
```bash
echo $PATH
which mosis
```

### "Authentication failed"

Re-login:
```bash
mosis logout
mosis login
```

### "Build failed: Invalid manifest"

Run validation for details:
```bash
mosis validate --strict
```

### "Network error"

Check connectivity:
```bash
mosis doctor
curl -I https://api.omixlab.com/health
```

## See Also

- [Getting Started](getting-started.md) - First app tutorial
- [Publishing Guide](guides/publishing.md) - Submission tips
- [API Reference](api/lua-api.md) - Lua API documentation