add documentation site with markdown rendering (M12)
This commit is contained in:
576
portal/internal/web/docs/cli.md
Normal file
576
portal/internal/web/docs/cli.md
Normal file
@@ -0,0 +1,576 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user