sloss-cli 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # sloss-cli
 
-Command-line interface for [Sloss](https://github.com/aualdrich/sloss) — a self-hosted IPA/APK distribution server inspired by Diawi.
+Command-line interface for [Sloss](https://github.com/aualdrich/sloss) — a self-hosted build distribution server for Expo apps. Supports iOS and Android.
 
 ## Install
 
@@ -11,43 +11,167 @@ npm install -g sloss-cli
 Or as a project dependency:
 
 ```bash
-npm install sloss-cli
+npm install --save-dev sloss-cli
 # or
-bun add sloss-cli
+bun add --dev sloss-cli
 ```
 
-## Quick Start
+## Setup
+
+### 1. Create a Sloss account
+
+Sign up at your team's Sloss instance (e.g. `https://sloss.example.com/signup`). After signing up, you'll receive an API key on the onboarding page. You can also find it under **Settings → API Key**.
+
+### 2. Authenticate the CLI
 
 ```bash
-# Authenticate (saves API key to ~/.config/sloss/credentials.json)
 sloss login
+```
+
+This prompts for your email and password, fetches your API key, and saves it to `~/.config/sloss/credentials.json`. You only need to do this once per machine.
+
+Alternatively, set the `SLOSS_API_KEY` environment variable or pass `--api-key` to any command.
+
+### 3. Add `.sloss.json` to your Expo project
+
+Create a `.sloss.json` file in your Expo project root (next to `app.json`):
+
+```json
+{
+  "type": "expo",
+  "app_name": "MyApp",
+  "bundle_id": "com.mycompany.myapp",
+  "version_file": "app.version.json",
+  "profiles": {
+    "development": {
+      "bundle_id_suffix": ".dev"
+    },
+    "preview": {
+      "bundle_id_suffix": ".preview"
+    },
+    "production": {
+      "bundle_id_suffix": ""
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `type` | Always `"expo"` |
+| `app_name` | Display name for the build on Sloss |
+| `bundle_id` | Base bundle identifier |
+| `version_file` | Path to a JSON file containing `version` and `buildNumber` (relative to project root) |
+| `profiles` | Build profile config — `bundle_id_suffix` is appended to `bundle_id` per profile |
+
+### 4. Create `app.version.json`
+
+Sloss reads version info from a dedicated file so the build agent can bump versions independently:
+
+```json
+{
+  "version": "1.0.0",
+  "buildNumber": "1"
+}
+```
+
+Reference this in your `app.json` / `app.config.js` so Expo picks it up:
+
+```js
+// app.config.js
+const version = require('./app.version.json');
+
+module.exports = {
+  expo: {
+    version: version.version,
+    ios: { buildNumber: String(version.buildNumber) },
+    android: { versionCode: parseInt(version.buildNumber, 10) },
+    // ... rest of your config
+  },
+};
+```
+
+## Usage
+
+### Queue a build
+
+From your Expo project directory:
+
+```bash
+# iOS development build (default)
+sloss build
+
+# Android preview build
+sloss build --platform android --profile preview
+
+# Production build with minor version bump
+sloss build --profile production --bump minor
+```
+
+The CLI packages your project via `git archive`, uploads it to Sloss, and a build agent picks it up. You'll get a link to the build page with live logs.
+
+#### Build options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--platform <platform>` | `ios` | `ios` or `android` |
+| `--profile <profile>` | `development` | `development`, `preview`, or `production` |
+| `--bump <type>` | `patch` | Version bump for production builds: `patch`, `minor`, or `major` |
+| `--dir <path>` | `.` | Project directory (if not running from project root) |
 
-# List recent builds
+### List builds
+
+```bash
 sloss list
+sloss list --limit 20
+```
+
+### Get build details
 
+```bash
+sloss info <build-id>
+```
+
+### Upload a pre-built artifact
+
+If you already have an IPA or APK (e.g. from a local build):
+
+```bash
 # Upload an IPA
-sloss upload path/to/App.ipa --platform ios --profile preview
+sloss upload ./build/MyApp.ipa --platform ios --profile preview
 
 # Upload an APK
-sloss upload path/to/app.apk --platform android --profile development
+sloss upload ./build/app-release.apk --platform android --profile production
+```
 
-# Get build details
-sloss info <build-id>
+#### Upload options
 
-# Delete a build
+| Flag | Description |
+|------|-------------|
+| `--platform <platform>` | **Required.** `ios` or `android` |
+| `--profile <profile>` | Build profile: `development`, `preview`, or `production` |
+| `--app-name <name>` | App display name |
+| `--version <version>` | Version string |
+| `--build-number <number>` | Build number |
+
+### Delete a build
+
+```bash
 sloss delete <build-id>
 ```
 
 ## Authentication
 
 API key resolution order (highest → lowest priority):
+
 1. `--api-key` CLI flag
 2. `SLOSS_API_KEY` environment variable
 3. `~/.config/sloss/credentials.json` (saved by `sloss login`)
 
 ## Server URL
 
-URL resolution order:
+URL resolution order (highest → lowest priority):
+
 1. `--url` CLI flag
 2. `SLOSS_URL` environment variable
 3. `~/.config/sloss/credentials.json`
@@ -55,40 +179,53 @@ URL resolution order:
 
 ## Global Options
 
-```
---api-key <key>   Override API key
---url <url>       Override server URL
---json            Output as JSON
---version         Show version
---help            Show help
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override API key |
+| `--url <url>` | Override server URL |
+| `--json` | Output as JSON |
+| `--version` | Show CLI version |
+| `--help` | Show help |
+
+## How It Works
+
+1. `sloss build` reads `.sloss.json` from your project root
+2. Your committed source is packaged into a tarball via `git archive`
+3. The tarball is uploaded to your Sloss server
+4. A build agent picks up the job and builds it locally using Xcode (iOS) or Gradle (Android)
+5. The finished IPA/APK is uploaded back to Sloss
+6. You get a build page with install links and QR codes for on-device installation
+
+## OpenClaw Skill
+
+This package includes an [OpenClaw](https://openclaw.ai) skill so your AI agent can use the Sloss CLI. After installing `sloss-cli`, add the skill directory to your OpenClaw config:
+
+```json5
+// ~/.openclaw/openclaw.json
+{
+  skills: {
+    load: {
+      extraDirs: ["./node_modules/sloss-cli/skills"]
+    }
+  }
+}
 ```
 
-## Publishing to npm
-
-Prerequisites:
-- An [npm](https://www.npmjs.com) account with publish access
-- An npm access token (Granular token with "Bypass 2FA" enabled, or an Automation classic token)
+Or copy the skill into your workspace:
 
 ```bash
-# Set your npm token
-echo "//registry.npmjs.org/:_authToken=YOUR_TOKEN" > ~/.npmrc
-
-# Bump version (patch/minor/major)
-npm version patch
-
-# Publish
-npm publish --access public
+cp -r ./node_modules/sloss-cli/skills/sloss <workspace>/skills/sloss
 ```
 
-The package is published as [`sloss-cli`](https://www.npmjs.com/package/sloss-cli) under the `front-porch-software` npm account.
+The skill is also available on [ClawHub](https://clawhub.com):
 
-### What gets published
-
-Only `bin/`, `src/`, and `README.md` are included in the npm package (controlled by `files` in `package.json`). Build scripts and other development files are excluded.
+```bash
+clawhub install sloss
+```
 
 ## Related
 
-- **[Sloss Server](https://github.com/aualdrich/sloss)** — The distribution server that this CLI talks to
+- **[Sloss Server](https://github.com/aualdrich/sloss)** — The self-hosted distribution server
 
 ## License
 

package/package.json

@@ -1,22 +1,33 @@
 {
   "name": "sloss-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "CLI for Sloss — a self-hosted IPA/APK distribution server",
   "type": "module",
   "bin": {
-    "sloss": "./bin/sloss.js"
+    "sloss": "bin/sloss.js"
   },
   "files": [
     "bin/",
     "src/",
+    "skills/",
     "README.md"
   ],
-  "keywords": ["sloss", "ios", "android", "ipa", "apk", "build", "distribution", "testflight", "diawi"],
+  "keywords": [
+    "sloss",
+    "ios",
+    "android",
+    "ipa",
+    "apk",
+    "build",
+    "distribution",
+    "testflight",
+    "diawi"
+  ],
   "author": "Front Porch Software",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/aualdrich/sloss-cli.git"
+    "url": "git+https://github.com/aualdrich/sloss-cli.git"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/sloss/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: sloss
+description: "Build, distribute, and manage Expo app builds (iOS & Android) via the Sloss CLI. Use when queuing builds, listing builds, uploading artifacts, checking build status, or managing the Sloss build server."
+homepage: https://github.com/aualdrich/sloss-cli
+metadata: {"openclaw":{"emoji":"🏭","requires":{"bins":["sloss"]},"install":[{"id":"npm","kind":"node","package":"sloss-cli","bins":["sloss"],"label":"Install Sloss CLI (npm)"}]}}
+---
+
+# Sloss — Build Distribution for Expo Apps
+
+Sloss is a self-hosted build distribution server for Expo apps (iOS & Android). The `sloss` CLI queues builds, uploads artifacts, and manages builds from the terminal.
+
+## Prerequisites
+
+1. `sloss` CLI installed (`sloss --version` to verify)
+2. A Sloss server instance (self-hosted)
+3. An account on the Sloss server with an API key
+
+## Authentication
+
+```bash
+# Login once — saves API key to ~/.config/sloss/credentials.json
+sloss login
+```
+
+API key resolution (highest → lowest priority):
+1. `--api-key` flag
+2. `SLOSS_API_KEY` environment variable
+3. `~/.config/sloss/credentials.json`
+
+Server URL resolution (highest → lowest priority):
+1. `--url` flag
+2. `SLOSS_URL` environment variable
+3. `~/.config/sloss/credentials.json`
+
+## Queue a Build
+
+Run from the Expo project root (requires `.sloss.json` config file):
+
+```bash
+# iOS development build (default)
+sloss build
+
+# Android preview build
+sloss build --platform android --profile preview
+
+# Production build with minor version bump
+sloss build --profile production --bump minor
+
+# Build from a different directory
+sloss build --dir /path/to/expo/project
+```
+
+### Build options
+
+| Flag | Default | Values |
+|------|---------|--------|
+| `--platform` | `ios` | `ios`, `android` |
+| `--profile` | `development` | `development`, `preview`, `production` |
+| `--bump` | `patch` | `patch`, `minor`, `major` |
+| `--dir` | `.` | Path to project root |
+
+### Build flow
+
+1. CLI reads `.sloss.json` from the project root
+2. Source is packaged via `git archive` (respects `.gitignore`)
+3. Tarball is uploaded to the Sloss server
+4. A build agent picks up the job and builds locally (Xcode for iOS, Gradle for Android)
+5. The finished IPA/APK is uploaded back to Sloss
+6. A build page with live logs and install links is available on the server
+
+## List Builds
+
+```bash
+sloss list
+sloss list --limit 20
+```
+
+## Build Details
+
+```bash
+sloss info <build-id>
+```
+
+## Upload a Pre-Built Artifact
+
+If you already have an IPA or APK:
+
+```bash
+# Upload an IPA
+sloss upload ./App.ipa --platform ios --profile preview
+
+# Upload an APK
+sloss upload ./app.apk --platform android --profile development
+```
+
+Upload options:
+
+| Flag | Description |
+|------|-------------|
+| `--platform` | **Required.** `ios` or `android` |
+| `--profile` | `development`, `preview`, or `production` |
+| `--app-name` | App display name |
+| `--version` | Version string |
+| `--build-number` | Build number |
+
+## Delete a Build
+
+```bash
+sloss delete <build-id>
+```
+
+## Project Configuration
+
+### `.sloss.json`
+
+Place in the Expo project root:
+
+```json
+{
+  "type": "expo",
+  "app_name": "MyApp",
+  "bundle_id": "com.example.myapp",
+  "version_file": "app.version.json",
+  "profiles": {
+    "development": { "bundle_id_suffix": ".dev" },
+    "preview": { "bundle_id_suffix": ".preview" },
+    "production": { "bundle_id_suffix": "" }
+  }
+}
+```
+
+### `app.version.json`
+
+```json
+{
+  "version": "1.0.0",
+  "buildNumber": "1"
+}
+```
+
+Reference this in `app.config.js` so Expo picks it up:
+
+```js
+const version = require('./app.version.json');
+module.exports = {
+  expo: {
+    version: version.version,
+    ios: { buildNumber: String(version.buildNumber) },
+    android: { versionCode: parseInt(version.buildNumber, 10) },
+  },
+};
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override API key |
+| `--url <url>` | Override server URL |
+| `--json` | JSON output |
+| `--version` | Show CLI version |
+| `--help` | Show help |
+
+## Output Formats
+
+All commands support `--json` for structured JSON output:
+
+```bash
+sloss list --json
+sloss info <build-id> --json
+```