@ossy/cli 1.16.9 → 1.16.11

package/README.md

@@ -1,21 +1,108 @@
 # @ossy/cli
 
-Unified CLI for the Ossy platform: app build and CMS workflows.
+Unified CLI for the Ossy platform.
 
-## Commands
+## Install
 
-| Command | Description |
-|---------|-------------|
-| `init [dir]` | Scaffold a new Ossy app (default: current directory) |
-| `build` | Production build |
-| `publish` | Queue a container deployment via `@ossy/deployment-tools` (**temporary**; see below), then upload `resourceTemplates` and **site build artifacts** (S3 presign + CMS resource) when `workspaceId` is set |
-| `cms upload` | Upload resource templates only (same API as publish’s upload step) |
-| `cms validate` | Validate ossy config and resource templates |
+```bash
+npm install -g @ossy/cli
+```
+
+After install, the `ossy` command is on your PATH:
+
+```bash
+ossy --version
+ossy --help
+ossy <command> --help
+```
+
+For one-off use without installing, you can still run `npx @ossy/cli <command>`.
+
+## How the CLI is organized
+
+The contract for everything the platform can do is the **SDK action POJO** in [`@ossy/sdk`](../sdk) (`{ id, endpoint, method, payload }`). The CLI is one channel onto that catalog, organized in three layers:
+
+1. **Local utilities** — no API call, or per-machine state. `init`, `build`, `auth`, `workspace`, `cms validate`.
+2. **Action dispatcher** — `call <action.id>` invokes any action in the SDK catalog. New endpoints added to the SDK are callable from the terminal with no extra CLI wiring.
+3. **High-level workflows** — verbs that wrap one or more actions and add value the dispatcher doesn't (reading `src/config.js`, formatting output for CI, multi-step pipelines). Each workflow's docs name the underlying action(s) so you can drop down to `ossy call` if you outgrow the verb.
+
+| Layer | Command | Description |
+|-------|---------|-------------|
+| Local | `auth login \| logout \| status` | Save / delete / inspect the Ossy API token under `~/.config/ossy/credentials.json` |
+| Local | `workspace use <id> \| list \| current` | Manage the active workspace (saved to `~/.config/ossy/config.json`) |
+| Local | `init [dir]` | Scaffold a new Ossy app (default: current directory) |
+| Local | `build` | Production build of the app in the current directory |
+| Local | `cms validate` | Validate `src/config.js` (`workspaceId`, `resourceTemplates`) without calling the API |
+| Dispatcher | `call <action.id>` | Invoke any Ossy SDK action by id (`ossy call --help` for the full catalog) |
+| Workflow | `cms upload` | Read `resourceTemplates` from `src/config.js` and call `workspaces.import-resource-templates` |
+| Workflow | `registry ecr-push-credentials` | Call `registry.ecr-push-credentials`, format for `docker login` or GitHub Actions |
+| Workflow | `publish` | Queue a deployment via `@ossy/deployment-tools` (**temporary**; see below), then run the resource-template and site-artifact uploads |
+
+If you need an endpoint that no verb wraps, reach for `ossy call` — it's the universal channel.
+
+## Auth and active workspace
+
+Once installed, the recommended flow is to log in once and pick an active workspace; subsequent commands inherit those:
+
+```bash
+ossy auth login                      # paste your Ossy API token
+ossy workspace list                  # see workspaces you can access
+ossy workspace use <workspace-id>    # set the active one
+ossy auth status                     # confirm
+```
+
+Credentials live in `~/.config/ossy/credentials.json` (`chmod 600`); the active workspace lives in `~/.config/ossy/config.json`. Both honor `XDG_CONFIG_HOME`.
+
+Resolution order for every command that needs auth:
+1. `--authentication` / `-a` flag
+2. `OSSY_API_KEY` env var
+3. Saved credentials
+
+Resolution order for the workspace id (when a command isn't reading it from `src/config.js`):
+1. `--workspace-id` / `-w` flag
+2. `OSSY_WORKSPACE_ID` env var
+3. Saved active workspace
+
+So existing CI scripts that set `OSSY_API_KEY` keep working unchanged; you only need `ossy auth login` for interactive use.
+
+## Generic dispatcher: `ossy call`
+
+`ossy call` invokes any Ossy API action by id. The action catalog comes from `@ossy/sdk`, so any new endpoint added to the SDK is callable from the terminal with no extra wiring.
+
+```bash
+# Discover what's available
+ossy call --help                                  # full catalog, grouped by domain
+ossy call resources.create --help                 # one action's method, endpoint, default payload
+
+# Read calls
+ossy call workspaces.get-current
+ossy call resources.list --search 'location=/docs'
+
+# Write calls — flag names map to payload keys (--first-name -> firstName)
+ossy call resources.create-directory --location /docs --name images
+ossy call workspaces.invite-user --email teammate@example.com
+
+# Use --json for nested or non-string payloads
+ossy call resources.update-content --id res_abc --json '{"content":{"title":"Hi"}}'
+
+# Upload a file: --file fills name/type/size as defaults, then PUTs the bytes
+# when the response carries content.uploadUrl (works for resources.upload,
+# resources.upload-named-version, etc.)
+ossy call resources.upload --location /docs --file ./hero.jpg
+ossy call resources.upload-named-version --id res_abc --name medium --file ./hero.jpg
+
+# Per-call overrides (otherwise resolved from `ossy auth login` / `ossy workspace use`)
+ossy call workspaces.get-all -a <jwt> --api-url http://localhost:3001/api/v0
+```
+
+Output is JSON pretty-printed to stdout on success. Errors go to stderr with a non-zero exit. Add `--raw` to get the response body verbatim (useful for piping non-JSON responses).
+
+`--file <path>` is a shortcut for upload-style actions: the CLI stats the file, fills `name`/`type`/`size` *as defaults* (any explicit `--name` / `--type` / `--size` flag wins), and after the dispatch it PUTs the bytes to `result.content.uploadUrl` with the right `Content-Type`/`Content-Length`. If the response doesn't include an upload URL, the bytes are skipped and a warning is printed.
 
 ## App: build
 
 ```bash
-npx @ossy/cli build
+ossy build
 ```
 
 Options: e.g. `--config` for `src/config.js`. See `packages/app/README.md` for app build behavior.
@@ -24,6 +111,8 @@ Options: e.g. `--config` for `src/config.js`. See `packages/app/README.md` for a
 
 Publishes a site by sending a deployment request to your platform queue (same as `npx @ossy/deployment-tools deployment deploy`). Run from the **website package** directory (where `src/config.js` lives) so domain/platform can be read automatically.
 
+**This is a multi-step workflow, not a single SDK action.** It shells out to `@ossy/deployment-tools` for the deploy and then performs two CMS uploads (resource templates → `workspaces.import-resource-templates`; site build artifacts → `/site-artifacts/presign-batch` + `/site-artifacts/commit-batch`). The deploy step is **temporary** — see *Future direction* below.
+
 ### Temporary: no execution of `src/config.js` for CMS steps
 
 After deploy succeeds, **`publish`** still needs **`workspaceId`**, **`apiUrl`** (optional, for absolute URLs), and **`resourceTemplates`** from `src/config.js`. Those values are **not** loaded with `import()` anymore: running the real config in plain Node would execute imports such as `@ossy/themes`, which are only meant to be resolved during **`ossy build`** (Rollup).
@@ -51,7 +140,7 @@ Container deploys assume **Amazon ECR** in **`deployments.json`** (`registry` li
 cd packages/my-website
 export OSSY_API_KEY=<ossy-api-jwt>   # or pass --authentication <ossy-api-jwt>
 
-npx @ossy/cli publish \
+ossy publish \
   --platforms-path ../infrastructure/platforms.json \
   --deployments-path "../infrastructure/deployments/**/*.json"
 ```
@@ -74,10 +163,16 @@ Requires network access so `npx` can run `@ossy/deployment-tools`.
 
 Upload resource templates to your workspace so they can be used in the UI.
 
+Wraps the SDK action **`workspaces.import-resource-templates`** and adds: reading `resourceTemplates` and `workspaceId` from `src/config.js` (so you don't have to inline the templates JSON yourself). If you already have the templates as a JSON object, the equivalent dispatcher call is:
+
+```bash
+ossy call workspaces.import-resource-templates --json '{"templates":[…]}'
+```
+
 Prefer **`--authentication` / `-a`** for the **Ossy API JWT** (same as **`publish`**); it matches **`OSSY_API_KEY`** in CI.
 
 ```bash
-npx @ossy/cli cms upload --authentication <ossy-api-jwt> --config src/config.js
+ossy cms upload --authentication <ossy-api-jwt> --config src/config.js
 # optional: --api-url https://api.ossy.se/api/v0  (or set OSSY_API_URL)
 # In CI you may omit --authentication when OSSY_API_KEY is set
 ```
@@ -119,7 +214,7 @@ jobs:
 Validate an ossy config file before uploading:
 
 ```bash
-npx @ossy/cli cms validate --config src/config.js
+ossy cms validate --config src/config.js
 ```
 
 When **`--config`** is omitted, **`./src/config.js`** is used if it exists.
@@ -132,13 +227,32 @@ When **`--config`** is omitted, **`./src/config.js`** is used if it exists.
 | --config, -c | App config (`workspaceId`, `resourceTemplates`, …) | Optional if `./src/config.js` exists |
 | --api-url | API base URL for upload (`…/api/v0`) | No |
 
+## Registry: ecr-push-credentials
+
+Fetch a short-lived ECR password so CI can `docker login` and `docker push` to the workspace's ECR registry.
+
+Wraps the SDK action **`registry.ecr-push-credentials`** and adds: response validation, JSON pretty-printing, and a `--format github-actions` mode that writes `registry`/`username`/`password`/`expires_at` to `$GITHUB_OUTPUT` and emits `::add-mask::<password>` so the secret never appears in logs.
+
+```bash
+ossy registry ecr-push-credentials                      # JSON to stdout
+ossy registry ecr-push-credentials --format github-actions   # writes to $GITHUB_OUTPUT
+```
+
+Auth and workspace are resolved from the usual chain (`-a` flag → `OSSY_API_KEY` → saved credentials; `-w` flag → `OSSY_WORKSPACE_ID` → saved active workspace). The plain dispatcher equivalent is:
+
+```bash
+ossy call registry.ecr-push-credentials
+```
+
+…but you lose the GitHub Actions output formatting and the `::add-mask::` line, so prefer the verb in CI.
+
 ## init
 
 Scaffold a new Ossy app:
 
 ```bash
-npx @ossy/cli init
-npx @ossy/cli init my-app
+ossy init
+ossy init my-app
 ```
 
 Creates `src/home.page.jsx`, `src/config.js`, and `package.json` (if missing).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/cli",
-  "version": "1.16.9",
+  "version": "1.16.11",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ossy-se/packages.git"
@@ -15,10 +15,13 @@
   },
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
   "license": "MIT",
-  "bin": "./src/index.js",
+  "bin": {
+    "ossy": "./src/index.js"
+  },
   "dependencies": {
     "@babel/parser": "^7.28.6",
-    "@ossy/app": "^1.16.9",
+    "@ossy/app": "^1.16.11",
+    "@ossy/sdk": "^1.16.11",
     "arg": "^5.0.2",
     "glob": "^10.3.10"
   },
@@ -30,5 +33,5 @@
     "/src",
     "README.md"
   ],
-  "gitHead": "be7612ac40cc49e027b0e417938cda738e19cd58"
+  "gitHead": "17a1a491a5239502f989b3745dab7a6c8ae17076"
 }

package/src/auth/cli.js

@@ -0,0 +1,135 @@
+import readline from 'node:readline/promises'
+import { stdin as input, stdout as output } from 'node:process'
+import arg from 'arg'
+import { logInfo, logError } from '../log.js'
+import {
+  readCredentials,
+  writeCredentials,
+  deleteCredentials,
+  getAuth,
+  getApiUrl,
+  getWorkspaceId,
+  describeStatePaths,
+} from '../state.js'
+
+function stripBearer (t) {
+  return String(t ?? '').trim().replace(/^Bearer\s+/i, '').trim()
+}
+
+async function promptHidden (question) {
+  // Tokens contain dots; avoid leaking partial input in shell history. Echo is left on
+  // because Node's tty masking is fiddly across platforms — paste-and-press-enter is
+  // the documented flow. We could revisit with a real prompt lib later.
+  const rl = readline.createInterface({ input, output })
+  try {
+    return (await rl.question(question)).trim()
+  } finally {
+    rl.close()
+  }
+}
+
+async function login (options) {
+  const parsed = arg({
+    '--token': String,
+    '-t': '--token',
+    '--api-url': String,
+  }, { argv: options })
+
+  let token = parsed['--token']
+  if (!token) {
+    if (!input.isTTY) {
+      logError({
+        message:
+          '[@ossy/cli] auth login: pass --token <jwt> or run interactively in a TTY.',
+      })
+      process.exit(1)
+    }
+    token = await promptHidden('Paste your Ossy API token: ')
+  }
+
+  const normalized = stripBearer(token)
+  if (!normalized) {
+    logError({ message: '[@ossy/cli] auth login: empty token.' })
+    process.exit(1)
+  }
+
+  const apiUrl = getApiUrl({ flag: parsed['--api-url'] })
+
+  let me = null
+  try {
+    const res = await fetch(`${apiUrl}/users/me`, {
+      headers: { Authorization: normalized, 'Content-Type': 'application/json' },
+    })
+    if (!res.ok) {
+      logError({
+        message: `[@ossy/cli] auth login: token rejected by ${apiUrl}/users/me (HTTP ${res.status})`,
+      })
+      process.exit(1)
+    }
+    me = await res.json().catch(() => null)
+  } catch (error) {
+    logError({ message: `[@ossy/cli] auth login: could not reach ${apiUrl}`, error })
+    process.exit(1)
+  }
+
+  writeCredentials({ apiUrl, token: normalized })
+  logInfo({
+    message: `[@ossy/cli] Logged in as ${me?.email || me?.id || 'user'} on ${apiUrl}`,
+  })
+}
+
+function logout () {
+  deleteCredentials()
+  logInfo({ message: '[@ossy/cli] Logged out' })
+}
+
+async function status () {
+  const creds = readCredentials()
+  const paths = describeStatePaths()
+  const apiUrl = getApiUrl()
+  const workspaceId = getWorkspaceId()
+
+  if (!creds?.token) {
+    console.log(
+      `Not logged in. Run \`ossy auth login\` to save credentials at ${paths.credentials}.`
+    )
+    return
+  }
+
+  const auth = getAuth()
+  let userInfo = null
+  let live = false
+  try {
+    const res = await fetch(`${apiUrl}/users/me`, {
+      headers: { Authorization: auth, 'Content-Type': 'application/json' },
+    })
+    if (res.ok) {
+      userInfo = await res.json().catch(() => null)
+      live = true
+    }
+  } catch {
+    // network failure → just report offline status
+  }
+
+  console.log(`API URL:    ${apiUrl}`)
+  console.log(
+    `User:       ${live ? (userInfo?.email || userInfo?.id || 'unknown') : '(token rejected — try `ossy auth login`)'}`
+  )
+  console.log(
+    `Workspace:  ${workspaceId || '(none — run `ossy workspace use <id>`)'}`
+  )
+  console.log(`Creds file: ${paths.credentials}`)
+  console.log(`Config:     ${paths.config}`)
+}
+
+export async function handler (args) {
+  const [sub, ...rest] = args
+  if (sub === 'login') return await login(rest)
+  if (sub === 'logout') return logout()
+  if (sub === 'status') return await status()
+  logError({
+    message:
+      '[@ossy/cli] auth: unknown subcommand. Use: ossy auth login | logout | status',
+  })
+  process.exit(1)
+}

package/src/call/cli.js

@@ -0,0 +1,327 @@
+import { readFile } from 'node:fs/promises'
+import * as Sdk from '@ossy/sdk'
+import { logError } from '../log.js'
+import { getAuth, getApiUrl, getWorkspaceId } from '../state.js'
+import { prepareFileUpload } from '../file.js'
+
+const ACTIONS = Object.values(Sdk).filter(
+  (v) =>
+    v
+    && typeof v === 'object'
+    && typeof v.id === 'string'
+    && typeof v.endpoint === 'string'
+    && typeof v.method === 'string'
+)
+
+const ACTION_BY_ID = new Map(ACTIONS.map((a) => [a.id, a]))
+
+function listActionsByDomain () {
+  const grouped = new Map()
+  for (const action of ACTIONS) {
+    const domain = action.id.split('.')[0]
+    if (!grouped.has(domain)) grouped.set(domain, [])
+    grouped.get(domain).push(action.id)
+  }
+  for (const [, ids] of grouped) ids.sort()
+  return new Map([...grouped.entries()].sort(([a], [b]) => a.localeCompare(b)))
+}
+
+function buildHelp () {
+  const grouped = listActionsByDomain()
+  const blocks = []
+  for (const [domain, ids] of grouped) {
+    blocks.push(`  ${domain}\n${ids.map((id) => `    ${id}`).join('\n')}`)
+  }
+  return `ossy call <action.id> [--key value]... [--json '{...}'] [options]
+
+Generic dispatcher for any Ossy API action. Flags become payload fields
+(--first-name -> firstName); --json '{...}' is merged on top.
+
+Options:
+  --json '{...}'         Provide payload as JSON (merged with --key value flags)
+  --file <path>          Attach a local file: derives name/type/size as defaults
+                         and PUTs the bytes if the response returns content.uploadUrl
+  -w, --workspace-id     Override active workspace id (sent as workspaceId header)
+  -a, --authentication   Override API token (otherwise resolved from state/env)
+  --api-url              Override API base URL
+  --raw                  Print response body without JSON pretty-printing
+
+Per-action help:
+  ossy call <action.id> --help
+
+Available actions:
+
+${blocks.join('\n\n')}
+`
+}
+
+function actionHelp (action) {
+  const def = action.payload ? `Default payload:\n  ${JSON.stringify(action.payload)}\n\n` : ''
+  return `${action.id}  ${action.method} ${action.endpoint}
+
+${def}Examples:
+  ossy call ${action.id} --key value --other value
+  ossy call ${action.id} --json '{"key":"value"}'
+`
+}
+
+function kebabToCamel (str) {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+const RESERVED_FLAGS_NEEDING_VALUE = new Set([
+  '--json',
+  '--workspace-id', '-w',
+  '--authentication', '-a',
+  '--api-url',
+  '--file',
+])
+
+function parseCallArgs (argv) {
+  const out = {
+    actionId: null,
+    payload: {},
+    workspaceId: null,
+    authentication: null,
+    apiUrl: null,
+    raw: false,
+    json: null,
+    file: null,
+    explicitPayloadKeys: new Set(),
+    help: false,
+  }
+
+  let i = 0
+  while (i < argv.length) {
+    const arg = argv[i]
+
+    if (arg === '--help' || arg === '-h') {
+      out.help = true
+      i++
+      continue
+    }
+    if (arg === '--raw') {
+      out.raw = true
+      i++
+      continue
+    }
+
+    // `--key=value` form, including reserved flags
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const eq = arg.indexOf('=')
+      const key = arg.slice(2, eq)
+      const value = arg.slice(eq + 1)
+      if (key === 'json') out.json = value
+      else if (key === 'workspace-id') out.workspaceId = value
+      else if (key === 'authentication') out.authentication = value
+      else if (key === 'api-url') out.apiUrl = value
+      else if (key === 'file') out.file = value
+      else {
+        const camel = kebabToCamel(key)
+        out.payload[camel] = value
+        out.explicitPayloadKeys.add(camel)
+      }
+      i++
+      continue
+    }
+
+    // Reserved space-separated flags
+    if (RESERVED_FLAGS_NEEDING_VALUE.has(arg)) {
+      const value = argv[i + 1]
+      if (arg === '--json') out.json = value
+      else if (arg === '--workspace-id' || arg === '-w') out.workspaceId = value
+      else if (arg === '--authentication' || arg === '-a') out.authentication = value
+      else if (arg === '--api-url') out.apiUrl = value
+      else if (arg === '--file') out.file = value
+      i += 2
+      continue
+    }
+
+    // Action.id is the first non-flag positional
+    if (!arg.startsWith('-') && out.actionId === null) {
+      out.actionId = arg
+      i++
+      continue
+    }
+
+    // Generic --key (value | true)
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const camel = kebabToCamel(key)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith('-')) {
+        out.payload[camel] = true
+        out.explicitPayloadKeys.add(camel)
+        i++
+      } else {
+        out.payload[camel] = next
+        out.explicitPayloadKeys.add(camel)
+        i += 2
+      }
+      continue
+    }
+
+    // Stray positional after the action id — ignore
+    i++
+  }
+
+  if (out.json) {
+    let parsed
+    try {
+      parsed = JSON.parse(out.json)
+    } catch (e) {
+      throw new Error(`--json: invalid JSON (${e.message})`)
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('--json: must be a JSON object')
+    }
+    for (const k of Object.keys(parsed)) out.explicitPayloadKeys.add(k)
+    Object.assign(out.payload, parsed)
+  }
+
+  return out
+}
+
+function isResponseLike (value) {
+  return (
+    value
+    && typeof value === 'object'
+    && typeof value.status === 'number'
+    && typeof value.text === 'function'
+    && typeof value.headers === 'object'
+    && typeof value.headers.get === 'function'
+  )
+}
+
+async function call (args) {
+  let parsed
+  try {
+    parsed = parseCallArgs(args)
+  } catch (err) {
+    logError({ message: `[@ossy/cli] call: ${err.message}` })
+    process.exit(1)
+  }
+
+  if (parsed.help && !parsed.actionId) {
+    console.log(buildHelp())
+    return
+  }
+
+  if (!parsed.actionId) {
+    console.log(buildHelp())
+    return
+  }
+
+  const action = ACTION_BY_ID.get(parsed.actionId)
+  if (!action) {
+    logError({
+      message: `[@ossy/cli] call: unknown action "${parsed.actionId}". Run \`ossy call --help\` for the list.`,
+    })
+    process.exit(1)
+  }
+
+  if (parsed.help) {
+    console.log(actionHelp(action))
+    return
+  }
+
+  const auth = getAuth({ flag: parsed.authentication })
+  const apiUrl = getApiUrl({ flag: parsed.apiUrl })
+  const workspaceId = getWorkspaceId({ flag: parsed.workspaceId })
+
+  const sdk = Sdk.SDK.of({
+    apiUrl,
+    workspaceId: workspaceId || undefined,
+    authorization: auth || undefined,
+  })
+
+  let fileMeta = null
+  if (parsed.file) {
+    try {
+      fileMeta = prepareFileUpload(parsed.file)
+    } catch (err) {
+      logError({ message: `[@ossy/cli] call: ${err.message}` })
+      process.exit(1)
+    }
+    if (!parsed.explicitPayloadKeys.has('name')) parsed.payload.name = fileMeta.name
+    if (!parsed.explicitPayloadKeys.has('type')) parsed.payload.type = fileMeta.type
+    if (!parsed.explicitPayloadKeys.has('size')) parsed.payload.size = fileMeta.size
+  }
+
+  let result
+  try {
+    result = await sdk.makeRequest(action)(parsed.payload)
+  } catch (err) {
+    if (isResponseLike(err)) {
+      const text = await err.text().catch(() => '')
+      process.stderr.write(`HTTP ${err.status}${err.statusText ? ' ' + err.statusText : ''}\n`)
+      if (text) process.stderr.write(text + '\n')
+      process.exit(1)
+    }
+    if (typeof err === 'string') {
+      process.stderr.write(err + '\n')
+      process.exit(1)
+    }
+    if (err && err.message) {
+      process.stderr.write(`${err.message}\n`)
+      process.exit(1)
+    }
+    process.stderr.write(JSON.stringify(err) + '\n')
+    process.exit(1)
+  }
+
+  if (isResponseLike(result)) {
+    if (parsed.raw) {
+      const text = await result.text().catch(() => '')
+      if (text) process.stdout.write(text.endsWith('\n') ? text : text + '\n')
+    } else {
+      console.log(JSON.stringify({ status: result.status }, null, 2))
+    }
+    return
+  }
+
+  if (fileMeta) {
+    const uploadUrl = result && result.content && result.content.uploadUrl
+    if (uploadUrl) {
+      try {
+        const body = await readFile(fileMeta.absPath)
+        const putRes = await fetch(uploadUrl, {
+          method: 'PUT',
+          headers: {
+            'Content-Type': fileMeta.type,
+            'Content-Length': String(fileMeta.size),
+          },
+          body,
+        })
+        if (!putRes.ok) {
+          const t = await putRes.text().catch(() => '')
+          process.stderr.write(
+            `[@ossy/cli] call: upload PUT failed: HTTP ${putRes.status}${t ? ' — ' + t.slice(0, 200) : ''}\n`
+          )
+          process.exit(1)
+        }
+      } catch (err) {
+        process.stderr.write(`[@ossy/cli] call: upload PUT failed: ${err.message || err}\n`)
+        process.exit(1)
+      }
+    } else {
+      process.stderr.write(
+        '[@ossy/cli] call: --file was provided but the response did not include content.uploadUrl; nothing was uploaded.\n'
+      )
+    }
+  }
+
+  if (parsed.raw) {
+    process.stdout.write(
+      typeof result === 'string'
+        ? (result.endsWith('\n') ? result : result + '\n')
+        : JSON.stringify(result) + '\n'
+    )
+    return
+  }
+
+  console.log(JSON.stringify(result, null, 2))
+}
+
+export const handler = call
+export { parseCallArgs, ACTIONS, ACTION_BY_ID, listActionsByDomain, buildHelp, actionHelp }

package/src/cms/cli.js

@@ -3,6 +3,7 @@ import { pathToFileURL } from 'url'
 import arg from 'arg'
 import { logInfo, logError } from '../log.js'
 import { resolveAppConfigPath } from '../resolve-app-config-path.js'
+import { getAuth } from '../state.js'
 import {
   postResourceTemplates,
   resolveApiBaseUrlForUpload,
@@ -22,14 +23,13 @@ const upload = (options) => {
     '--api-url': String,
   }, { argv: options })
 
-  const token =
-    parsedArgs['--authentication'] || process.env.OSSY_API_KEY
+  const token = getAuth({ flag: parsedArgs['--authentication'] })
   const apiUrlFlag = parsedArgs['--api-url']
 
   if (!token) {
     logError({
       message:
-        '[@ossy/cli] No token provided. Use --authentication / -a or set OSSY_API_KEY',
+        '[@ossy/cli] No token provided. Use --authentication / -a, set OSSY_API_KEY, or run `ossy auth login`.',
     })
     process.exit(1)
   }

package/src/file.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** @type {Record<string, string>} */
+const MIME_BY_EXT = {
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.cjs': 'application/javascript',
+  '.css': 'text/css',
+  '.html': 'text/html',
+  '.htm': 'text/html',
+  '.json': 'application/json',
+  '.map': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain',
+  '.xml': 'application/xml',
+  '.webmanifest': 'application/manifest+json',
+  '.pdf': 'application/pdf',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+}
+
+/**
+ * Best-effort MIME type from extension. Falls back to `application/octet-stream`.
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function guessContentType (filePath) {
+  const ext = path.extname(filePath).toLowerCase()
+  return MIME_BY_EXT[ext] || 'application/octet-stream'
+}
+
+/**
+ * Stat a local file and derive metadata for an upload payload.
+ * Throws if the path doesn't exist or isn't a regular file.
+ * @param {string} filePath absolute or cwd-relative
+ * @returns {{ absPath: string, name: string, size: number, type: string }}
+ */
+export function prepareFileUpload (filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('--file: missing path')
+  }
+  const absPath = path.resolve(filePath)
+  let stat
+  try {
+    stat = fs.statSync(absPath)
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      throw new Error(`--file: not found: ${filePath}`)
+    }
+    throw new Error(`--file: cannot stat ${filePath}: ${err.message || err}`)
+  }
+  if (!stat.isFile()) {
+    throw new Error(`--file: not a regular file: ${filePath}`)
+  }
+  return {
+    absPath,
+    name: path.basename(absPath),
+    size: stat.size,
+    type: guessContentType(absPath),
+  }
+}

package/src/index.js

@@ -1,20 +1,156 @@
 #!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { build } from '@ossy/app'
+import * as Auth from './auth/cli.js'
+import * as Call from './call/cli.js'
 import * as Cms from './cms/cli.js'
 import * as Init from './init/cli.js'
 import { publish } from './publish/cli.js'
 import * as Registry from './registry/cli.js'
+import * as Workspace from './workspace/cli.js'
 
-const [,, command, ...restArgs] = process.argv
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+)
 
-if (!command) {
-  console.error(
-    '[@ossy/cli] No command provided. Usage: ossy build [--worker] | publish | registry <subcommand> | init | cms <subcommand>'
-  )
-  process.exit(1)
+const HELP = `ossy ${pkg.version}
+Command line tool for the Ossy platform.
+
+Usage:
+  ossy <command> [options]
+
+Local utilities:
+  auth <subcommand>       Sign in / out and check status: login | logout | status
+  workspace <subcommand>  Manage active workspace: use | list | current
+  init [dir]              Scaffold a new Ossy app
+  build                   Production build of the app in the current directory
+  cms validate            Validate src/config.js (workspaceId + resourceTemplates)
+
+Action dispatcher (any Ossy SDK action, no per-action wiring needed):
+  call <action.id>        Run \`ossy call --help\` for the full catalog
+
+Workflows (wrap one or more actions with extra ergonomics):
+  cms upload              Upload resource templates from src/config.js
+                          (wraps workspaces.import-resource-templates)
+  registry <subcommand>   ecr-push-credentials (wraps registry.ecr-push-credentials,
+                          adds --format github-actions and password masking)
+  publish                 Deploy via @ossy/deployment-tools, then upload
+                          resource templates and site build artifacts
+
+Options:
+  -h, --help              Show this help, or for a command: ossy <command> --help
+  -v, --version           Print the installed version
+`
+
+const SUBCOMMAND_HELP = {
+  auth: `ossy auth <subcommand>
+  Subcommands:
+    login    Save an Ossy API token under ~/.config/ossy/credentials.json
+    logout   Delete the saved token
+    status   Print logged-in user, active workspace, and config paths
+
+Options (login):
+  -t, --token   Ossy API JWT (otherwise prompts in a TTY)
+  --api-url     API base URL (default: https://api.ossy.se/api/v0)
+`,
+  workspace: `ossy workspace <subcommand>
+  Subcommands:
+    use <id>   Set the active workspace (saved to ~/.config/ossy/config.json)
+    list       List workspaces the current user can access
+    current    Print the active workspace id
+`,
+  init: `ossy init [dir]
+  Scaffold a new Ossy app in [dir] (defaults to current directory).
+  Creates src/home.page.jsx, src/config.js, and package.json (if missing).
+`,
+  build: `ossy build
+  Run the production build for the app in the current directory.
+  See the @ossy/app README for build options.
+`,
+  publish: `ossy publish [options]
+  Multi-step workflow: deploy via @ossy/deployment-tools (temporary), then
+  optionally upload resource templates and site build artifacts. The deploy
+  step is intended to go away once the platform reacts to artifact events;
+  the CMS upload steps are equivalent to:
+    workspaces.import-resource-templates  (resource templates)
+    /site-artifacts/presign-batch + /commit-batch  (site artifacts)
+
+Options:
+  -a, --authentication        Ossy API JWT (or set OSSY_API_KEY, or run \`ossy auth login\`)
+  -d, --domain                Site domain
+  -p, --platform              Target deployment platform
+  -c, --config                Path to src/config.js
+  --platforms-path            Path to platforms.json
+  --deployments-path          Glob for deployments JSON files
+  --all                       Deploy all sites for the platform
+  --skip-resource-templates   Skip post-deploy resource-template upload
+  --skip-site-artifacts       Skip post-deploy site-artifact upload
+  --site-artifacts-build-dir  Override the site build directory
+  --api-url                   API base URL for CMS calls
+`,
+  cms: `ossy cms <subcommand>
+  Subcommands:
+    upload    Upload resource templates from src/config.js to the workspace
+              (wraps the SDK action workspaces.import-resource-templates)
+    validate  Validate ossy app config and resource templates locally
+
+Options (upload):
+  -a, --authentication  Ossy API JWT (or set OSSY_API_KEY, or run \`ossy auth login\`)
+  -c, --config          Path to src/config.js
+  --api-url             API base URL for CMS calls
+
+Options (validate):
+  -c, --config          Path to src/config.js
+`,
+  registry: `ossy registry <subcommand>
+  Subcommands:
+    ecr-push-credentials  Fetch a short-lived ECR password for docker login
+                          (wraps the SDK action registry.ecr-push-credentials;
+                          adds --format github-actions and password masking)
+
+Options:
+  -a, --authentication  Ossy API JWT (or set OSSY_API_KEY, or run \`ossy auth login\`)
+  -w, --workspace-id    Workspace id (or set OSSY_WORKSPACE_ID, or run \`ossy workspace use\`)
+  --format              json | github-actions
+`,
+}
+
+const isHelpFlag = (a) => a === '--help' || a === '-h'
+const isVersionFlag = (a) => a === '--version' || a === '-v'
+
+const [, , command, ...restArgs] = process.argv
+
+if (command === undefined || isHelpFlag(command)) {
+  console.log(HELP)
+  process.exit(0)
+}
+
+if (isVersionFlag(command)) {
+  console.log(pkg.version)
+  process.exit(0)
+}
+
+if (restArgs.some(isHelpFlag) && SUBCOMMAND_HELP[command]) {
+  console.log(SUBCOMMAND_HELP[command])
+  process.exit(0)
 }
 
 const run = async () => {
+  if (command === 'auth') {
+    await Auth.handler(restArgs)
+    return
+  }
+  if (command === 'workspace') {
+    await Workspace.handler(restArgs)
+    return
+  }
+  if (command === 'call') {
+    await Call.handler(restArgs)
+    return
+  }
   if (command === 'registry') {
     await Registry.handler(restArgs)
     return
@@ -36,6 +172,7 @@ const run = async () => {
     return
   }
   console.error(`[@ossy/cli] Unknown command: ${command}`)
+  console.error('Run `ossy --help` for available commands.')
   process.exit(1)
 }
 

package/src/publish/cli.js

@@ -10,6 +10,7 @@ import {
 import { maybeUploadResourceTemplatesAfterPublish } from './resource-templates-after-publish.js'
 import { maybeUploadSiteArtifactsAfterPublish } from './site-artifacts-after-publish.js'
 import { requireCmsAuthentication } from '../cms/upload-resource-templates.js'
+import { getAuth } from '../state.js'
 
 const DEPLOYMENT_TOOLS = '@ossy/deployment-tools'
 
@@ -64,14 +65,14 @@ export async function publish (options) {
   let apiToken
   try {
     apiToken = requireCmsAuthentication(
-      parsedArgs['--authentication'] || process.env.OSSY_API_KEY,
+      getAuth({ flag: parsedArgs['--authentication'] }),
       'publish'
     )
   } catch (e) {
     logError({
       message:
         e?.message
-        || '[@ossy/cli] publish: pass --authentication (-a) or set OSSY_API_KEY (Ossy API JWT).',
+        || '[@ossy/cli] publish: pass --authentication (-a), set OSSY_API_KEY, or run `ossy auth login`.',
     })
     process.exit(1)
   }

package/src/publish/site-artifacts-after-publish.js

@@ -8,38 +8,11 @@ import {
   requireCmsAuthentication,
   resolveApiBaseUrlForUpload,
 } from '../cms/upload-resource-templates.js'
+import { guessContentType } from '../file.js'
 
 const MAX_FILES = 200
 
-/** @type {Record<string, string>} */
-const MIME_BY_EXT = {
-  '.js': 'application/javascript',
-  '.mjs': 'application/javascript',
-  '.cjs': 'application/javascript',
-  '.css': 'text/css',
-  '.html': 'text/html',
-  '.htm': 'text/html',
-  '.json': 'application/json',
-  '.map': 'application/json',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.ttf': 'font/ttf',
-  '.txt': 'text/plain',
-  '.xml': 'application/xml',
-  '.webmanifest': 'application/manifest+json',
-}
-
-export function guessContentType (filePath) {
-  const ext = path.extname(filePath).toLowerCase()
-  return MIME_BY_EXT[ext] || 'application/octet-stream'
-}
+export { guessContentType }
 
 /**
  * @param {string} buildDir absolute path to `build/` output

package/src/registry/ecr-push-credentials.js

@@ -1,6 +1,7 @@
 import arg from 'arg'
 import { appendFileSync } from 'fs'
 import { requireCmsAuthentication } from '../cms/upload-resource-templates.js'
+import { getAuth, getWorkspaceId } from '../state.js'
 
 const DEFAULT_API_URL = 'https://api.ossy.se/api/v0'
 
@@ -25,17 +26,17 @@ export async function ecrPushCredentials (options) {
   let token
   try {
     token = requireCmsAuthentication(
-      parsed['--authentication'] || process.env.OSSY_API_KEY,
+      getAuth({ flag: parsed['--authentication'] }),
       'registry ecr-push-credentials'
     )
   } catch (e) {
-    console.error(e?.message || '[@ossy/cli] registry ecr-push-credentials: need --authentication (-a) or OSSY_API_KEY')
+    console.error(e?.message || '[@ossy/cli] registry ecr-push-credentials: need --authentication (-a), OSSY_API_KEY, or `ossy auth login`')
     process.exit(1)
   }
 
-  const workspaceId = parsed['--workspace-id'] || process.env.OSSY_WORKSPACE_ID || ''
-  if (!workspaceId.trim()) {
-    console.error('[@ossy/cli] registry ecr-push-credentials: pass --workspace-id (-w) or set OSSY_WORKSPACE_ID')
+  const workspaceId = getWorkspaceId({ flag: parsed['--workspace-id'] })
+  if (!workspaceId) {
+    console.error('[@ossy/cli] registry ecr-push-credentials: pass --workspace-id (-w), set OSSY_WORKSPACE_ID, or run `ossy workspace use <id>`')
     process.exit(1)
   }
 
@@ -46,7 +47,7 @@ export async function ecrPushCredentials (options) {
     method: 'POST',
     headers: {
       authorization: token,
-      workspaceId: workspaceId.trim(),
+      workspaceId,
       'content-type': 'application/json',
     },
     body: '{}',

package/src/state.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const DEFAULT_API_URL = 'https://api.ossy.se/api/v0'
+
+function configDir () {
+  const xdg = process.env.XDG_CONFIG_HOME
+  if (xdg && xdg.trim()) return path.join(xdg.trim(), 'ossy')
+  return path.join(os.homedir(), '.config', 'ossy')
+}
+
+function ensureDir () {
+  const dir = configDir()
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  return dir
+}
+
+function credentialsPath () { return path.join(configDir(), 'credentials.json') }
+function configPath () { return path.join(configDir(), 'config.json') }
+
+/** @returns {{ apiUrl?: string, token?: string } | null} */
+export function readCredentials () {
+  try {
+    return JSON.parse(fs.readFileSync(credentialsPath(), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** @param {{ apiUrl?: string, token: string }} creds */
+export function writeCredentials (creds) {
+  ensureDir()
+  fs.writeFileSync(credentialsPath(), JSON.stringify(creds, null, 2), { mode: 0o600 })
+}
+
+export function deleteCredentials () {
+  try { fs.unlinkSync(credentialsPath()) } catch { /* not logged in */ }
+}
+
+/** @returns {{ workspaceId?: string } | null} */
+export function readConfig () {
+  try {
+    return JSON.parse(fs.readFileSync(configPath(), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** @param {{ workspaceId?: string }} cfg */
+export function writeConfig (cfg) {
+  ensureDir()
+  fs.writeFileSync(configPath(), JSON.stringify(cfg, null, 2))
+}
+
+function stripBearer (token) {
+  return String(token ?? '').trim().replace(/^Bearer\s+/i, '').trim()
+}
+
+/**
+ * Resolve the Ossy API JWT used for authenticated requests.
+ * Order: explicit flag > OSSY_API_KEY env > saved credentials.
+ * @param {{ flag?: string }} [opts]
+ * @returns {string | null}
+ */
+export function getAuth ({ flag } = {}) {
+  const fromFlag = stripBearer(flag)
+  if (fromFlag) return fromFlag
+  const fromEnv = stripBearer(process.env.OSSY_API_KEY)
+  if (fromEnv) return fromEnv
+  const fromFile = stripBearer(readCredentials()?.token)
+  if (fromFile) return fromFile
+  return null
+}
+
+/**
+ * Order: explicit absolute flag > OSSY_API_URL env > saved credentials > default.
+ * Relative paths in the flag are ignored (matches existing publish behavior).
+ * @param {{ flag?: string }} [opts]
+ * @returns {string}
+ */
+export function getApiUrl ({ flag } = {}) {
+  if (flag && /^https?:\/\//i.test(String(flag).trim())) {
+    return String(flag).trim().replace(/\/$/, '')
+  }
+  const fromEnv = String(process.env.OSSY_API_URL ?? '').trim()
+  if (fromEnv) return fromEnv.replace(/\/$/, '')
+  const fromFile = String(readCredentials()?.apiUrl ?? '').trim()
+  if (/^https?:\/\//i.test(fromFile)) return fromFile.replace(/\/$/, '')
+  return DEFAULT_API_URL
+}
+
+/**
+ * Order: explicit flag > OSSY_WORKSPACE_ID env > saved active workspace.
+ * Project-scoped commands (publish/cms) keep reading from src/config.js separately.
+ * @param {{ flag?: string }} [opts]
+ * @returns {string | null}
+ */
+export function getWorkspaceId ({ flag } = {}) {
+  const fromFlag = String(flag ?? '').trim()
+  if (fromFlag) return fromFlag
+  const fromEnv = String(process.env.OSSY_WORKSPACE_ID ?? '').trim()
+  if (fromEnv) return fromEnv
+  const fromFile = String(readConfig()?.workspaceId ?? '').trim()
+  if (fromFile) return fromFile
+  return null
+}
+
+export function describeStatePaths () {
+  return {
+    dir: configDir(),
+    credentials: credentialsPath(),
+    config: configPath(),
+  }
+}

package/src/workspace/cli.js

@@ -0,0 +1,84 @@
+import { logInfo, logError } from '../log.js'
+import {
+  readConfig,
+  writeConfig,
+  getAuth,
+  getApiUrl,
+  getWorkspaceId,
+} from '../state.js'
+
+function ensureAuth () {
+  const auth = getAuth()
+  if (!auth) {
+    logError({
+      message: '[@ossy/cli] Not logged in. Run `ossy auth login` first.',
+    })
+    process.exit(1)
+  }
+  return auth
+}
+
+function use (options) {
+  const id = options[0]
+  if (!id) {
+    logError({ message: '[@ossy/cli] workspace use: pass a workspace id.' })
+    process.exit(1)
+  }
+  writeConfig({ ...(readConfig() || {}), workspaceId: id })
+  logInfo({ message: `[@ossy/cli] Active workspace: ${id}` })
+}
+
+async function list () {
+  const auth = ensureAuth()
+  const apiUrl = getApiUrl()
+
+  let res
+  try {
+    res = await fetch(`${apiUrl}/workspaces`, {
+      headers: { Authorization: auth, 'Content-Type': 'application/json' },
+    })
+  } catch (error) {
+    logError({ message: `[@ossy/cli] workspace list: could not reach ${apiUrl}`, error })
+    process.exit(1)
+  }
+
+  if (!res.ok) {
+    logError({
+      message: `[@ossy/cli] workspace list: HTTP ${res.status} from ${apiUrl}/workspaces`,
+    })
+    process.exit(1)
+  }
+
+  const workspaces = await res.json().catch(() => null)
+  if (!Array.isArray(workspaces) || workspaces.length === 0) {
+    console.log('No workspaces found.')
+    return
+  }
+
+  const active = getWorkspaceId()
+  for (const w of workspaces) {
+    const marker = w.id === active ? '* ' : '  '
+    console.log(`${marker}${w.id}\t${w.name || ''}`)
+  }
+}
+
+function current () {
+  const id = getWorkspaceId()
+  if (!id) {
+    console.log('(no active workspace)')
+    return
+  }
+  console.log(id)
+}
+
+export async function handler (args) {
+  const [sub, ...rest] = args
+  if (sub === 'use') return use(rest)
+  if (sub === 'list') return await list()
+  if (sub === 'current') return current()
+  logError({
+    message:
+      '[@ossy/cli] workspace: unknown subcommand. Use: ossy workspace use <id> | list | current',
+  })
+  process.exit(1)
+}