@userland.fun/cli 0.1.0 → 0.1.2

package/README.md

@@ -21,8 +21,12 @@ userland signup --username <username>
 userland login --username <username>
 userland auth status
 userland auth save-key --username <username> --api-key <api-key>
+userland accounts list
+userland accounts use <account-id>
 userland apps publish examples/<example-slug>
+userland apps publish examples/<example-slug> --account <account-id>
 userland apps list
+USERLAND_ACCOUNT_ID=<account-id> userland apps list
 userland apps releases <app-id>
 userland apps rollback <app-id> <release-id>
 userland apps secrets set <app-id> <NAME> --value <value>
@@ -36,8 +40,12 @@ npm run userland -- signup --username <username>
 npm run userland -- login --username <username>
 npm run userland -- auth status
 npm run userland -- auth save-key --username <username> --api-key <api-key>
+npm run userland -- accounts list
+npm run userland -- accounts use <account-id>
 npm run userland -- apps publish examples/<example-slug>
+npm run userland -- apps publish examples/<example-slug> --account <account-id>
 npm run userland -- apps list
+npm run userland -- apps list --account <account-id>
 npm run userland -- apps releases <app-id>
 npm run userland -- apps rollback <app-id> <release-id>
 npm run userland -- apps secrets set <app-id> <NAME> --value <value>
@@ -46,6 +54,8 @@ npm run userland -- apps events <app-id>
 
 `signup`, `login`, and `auth save-key` save the API key to `~/.userland/credentials.json` with `0600` permissions. Account username and password are stored in the OS keychain: macOS Keychain, Windows Credential Manager, or Linux Secret Service through `secret-tool`. App commands prefer `USERLAND_API_KEY` when it is set, then fall back to the saved API key.
 
+Most users do not need to select an account. If no account is selected, the API uses the actor's default account. Team, client, and agency workflows can select an account with `--account <account-id>`, `USERLAND_ACCOUNT_ID`, or `userland accounts use <account-id>`. Platform account members manage apps, releases, secrets, billing, and settings; they are separate from app users inside a published app.
+
 ## Validation
 
 Build and inspect the publish tarball:

package/dist/index.js

@@ -9,6 +9,9 @@ const KEYCHAIN_SERVICE = "fun.userland.cli";
 const KEYCHAIN_ACCOUNT = "default";
 async function main() {
     const [command, ...args] = process.argv.slice(2);
+    if (isHelpCommand(command)) {
+        usage(0);
+    }
     if (command === "apps") {
         await appsCommand(args);
         return;
@@ -17,6 +20,10 @@ async function main() {
         await authCommand(args);
         return;
     }
+    if (command === "accounts") {
+        await accountsCommand(args);
+        return;
+    }
     if (command === "signup") {
         await signupCommand(args);
         return;
@@ -42,7 +49,7 @@ async function appsCommand(args) {
         return;
     }
     if (subcommand === "list") {
-        await listAppsCommand();
+        await listAppsCommand(rest);
         return;
     }
     if (subcommand === "releases") {
@@ -83,6 +90,18 @@ async function authCommand(args) {
     }
     usage(1);
 }
+async function accountsCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === "list") {
+        await listAccountsCommand();
+        return;
+    }
+    if (subcommand === "use") {
+        await useAccountCommand(rest);
+        return;
+    }
+    usage(1);
+}
 async function signupCommand(args) {
     const options = parseAuthOptions(args);
     const username = options.username ?? (await promptRequired("Username: "));
@@ -99,7 +118,8 @@ async function signupCommand(args) {
         await saveAccountCredentials({ username: response.username, password });
         const filePath = await saveCredentials({
             api_key: response.api_key,
-            api_base_url: await apiBaseUrl()
+            api_base_url: await apiBaseUrl(),
+            account_id: response.account_id ?? null
         });
         console.log(`Created Userland account ${response.username}`);
         console.log(`Saved API key to ${filePath}`);
@@ -119,10 +139,13 @@ async function loginCommand(args) {
         body: JSON.stringify({ username, password })
     });
     if (options.save !== false) {
+        const baseUrl = await apiBaseUrl();
+        const accountId = response.account_id ?? (await discoverDefaultAccountId(response.api_key, baseUrl).catch(() => undefined));
         await saveAccountCredentials({ username, password });
         const filePath = await saveCredentials({
             api_key: response.api_key,
-            api_base_url: await apiBaseUrl()
+            api_base_url: baseUrl,
+            account_id: accountId ?? null
         });
         console.log(`Saved API key to ${filePath}`);
         console.log(`Saved account login to ${accountCredentialStoreLabel()}`);
@@ -135,10 +158,16 @@ async function authStatusCommand() {
     const account = await readAccountCredentials();
     const filePath = credentialsPath();
     const apiKeySource = process.env.USERLAND_API_KEY ? "env" : credentials?.api_key ? "file" : "missing";
+    const selectedAccountId = process.env.USERLAND_ACCOUNT_ID ?? credentials?.account_id;
+    const accountSource = process.env.USERLAND_ACCOUNT_ID ? "env" : credentials?.account_id ? "file" : apiKeySource === "missing" ? "missing" : "default";
     console.log(`api_base_url=${await apiBaseUrl(credentials)}`);
     console.log(`api_key=${apiKeySource}`);
     console.log(`credentials_file=${filePath}`);
-    console.log(`account=${account ? "keychain" : "missing"}`);
+    console.log(`account=${accountSource}`);
+    if (selectedAccountId) {
+        console.log(`account_id=${selectedAccountId}`);
+    }
+    console.log(`account_login=${account ? "keychain" : "missing"}`);
     if (account?.username) {
         console.log(`username=${account.username}`);
     }
@@ -150,11 +179,30 @@ async function saveKeyCommand(args) {
     await saveAccountCredentials({ username, password: options.password });
     const filePath = await saveCredentials({
         api_key: apiKey,
-        api_base_url: await apiBaseUrl()
+        api_base_url: await apiBaseUrl(),
+        account_id: null
     });
     console.log(`Saved API key to ${filePath}`);
     console.log(`Saved account login to ${accountCredentialStoreLabel()}`);
 }
+async function listAccountsCommand() {
+    const response = await apiFetch("/v0/accounts", {
+        method: "GET"
+    });
+    for (const account of response.accounts) {
+        console.log(`${account.account_id}\t${account.role}\t${account.name}`);
+    }
+    console.log(`default_account_id=${response.default_account_id}`);
+}
+async function useAccountCommand(args) {
+    const accountId = args[0];
+    if (!accountId) {
+        usage(1);
+    }
+    const filePath = await saveCredentials({ account_id: accountId });
+    console.log(`selected_account_id=${accountId}`);
+    console.log(`credentials_file=${filePath}`);
+}
 async function publishCommand(args) {
     const dir = args[0];
     const options = parseOptions(args.slice(1));
@@ -165,7 +213,7 @@ async function publishCommand(args) {
     const response = await apiFetch(options.app ? `/v0/apps/${options.app}` : "/v0/apps", {
         method: "PUT",
         body: JSON.stringify(body)
-    });
+    }, { accountId: options.account, accountScoped: true });
     console.log(`Published ${response.origin}`);
     console.log(`app_id=${response.app_id}`);
     console.log(`release_id=${response.release_id}`);
@@ -175,10 +223,11 @@ async function publishCommand(args) {
         console.log(`activation_reasons=${response.activation.reasons.join("; ")}`);
     }
 }
-async function listAppsCommand() {
+async function listAppsCommand(args = []) {
+    const options = parseAccountOptions(args);
     const response = await apiFetch("/v0/apps", {
         method: "GET"
-    });
+    }, { accountId: options.account, accountScoped: true });
     for (const app of response.apps) {
         console.log(`${app.app_id}\t${app.live_release_id ?? ""}\t${app.updated_at}\t${app.name}\t${app.origin}`);
     }
@@ -188,9 +237,10 @@ async function releasesCommand(args) {
     if (!appId) {
         usage(1);
     }
+    const options = parseAccountOptions(args.slice(1));
     const response = await apiFetch(`/v0/apps/${appId}/releases`, {
         method: "GET"
-    });
+    }, { accountId: options.account, accountScoped: true });
     for (const release of response.releases) {
         const live = release.is_live ? " live" : "";
         console.log(`${release.release_id}${live}\t${release.activation_status}\t${release.created_at}\t${release.message ?? ""}`);
@@ -201,10 +251,11 @@ async function rollbackCommand(args) {
     if (!appId || !releaseId) {
         usage(1);
     }
+    const options = parseAccountOptions(args.slice(2));
     const response = await apiFetch(`/v0/apps/${appId}/rollback`, {
         method: "POST",
         body: JSON.stringify({ release_id: releaseId })
-    });
+    }, { accountId: options.account, accountScoped: true });
     console.log(`Rolled back ${response.origin}`);
     console.log(`app_id=${response.app_id}`);
     console.log(`release_id=${response.release_id}`);
@@ -224,7 +275,7 @@ async function setSecretCommand(args) {
     const response = await apiFetch(`/v0/apps/${appId}/secrets/${name}`, {
         method: "PUT",
         body: JSON.stringify({ value })
-    });
+    }, { accountId: options.account, accountScoped: true });
     console.log(`secret=${response.name}`);
     console.log(`present=${response.present}`);
     console.log(`updated_at=${response.updated_at}`);
@@ -247,7 +298,7 @@ async function eventsCommand(args) {
     const suffix = params.toString() ? `?${params.toString()}` : "";
     const response = await apiFetch(`/v0/apps/${appId}/events${suffix}`, {
         method: "GET"
-    });
+    }, { accountId: options.account, accountScoped: true });
     for (const event of response.events) {
         console.log(`${event.created_at}\t${event.severity}\t${event.type}\t${event.release_id ?? ""}\t${event.message}`);
     }
@@ -363,24 +414,41 @@ async function walk(dir) {
     }));
     return files.flat();
 }
-async function apiFetch(apiPath, init) {
+async function apiFetch(apiPath, init, options = {}) {
     const credentials = await readCredentials();
     const apiKey = process.env.USERLAND_API_KEY ?? credentials?.api_key;
     if (!apiKey) {
         throw new Error("USERLAND_API_KEY is required. Run `userland signup` or `userland login` to save credentials.");
     }
     const baseUrl = await apiBaseUrl(credentials);
+    const accountId = options.accountScoped ? selectedAccountId(options.accountId, credentials) : undefined;
+    const headers = {
+        authorization: `Bearer ${apiKey}`,
+        ...init.headers
+    };
+    if (accountId) {
+        headers["x-userland-account-id"] = accountId;
+    }
     return await requestJson(baseUrl, apiPath, {
         ...init,
-        headers: {
-            authorization: `Bearer ${apiKey}`,
-            ...init.headers
-        }
+        headers
     });
 }
 async function unauthenticatedApiFetch(apiPath, init) {
     return await requestJson(await apiBaseUrl(), apiPath, init);
 }
+async function discoverDefaultAccountId(apiKey, baseUrl) {
+    const response = await requestJson(baseUrl, "/v0/accounts", {
+        method: "GET",
+        headers: {
+            authorization: `Bearer ${apiKey}`
+        }
+    });
+    return response.default_account_id;
+}
+function selectedAccountId(explicitAccountId, credentials) {
+    return explicitAccountId ?? process.env.USERLAND_ACCOUNT_ID ?? credentials?.account_id;
+}
 async function requestJson(baseUrl, apiPath, init) {
     const response = await fetch(`${baseUrl.replace(/\/$/u, "")}${apiPath}`, {
         ...init,
@@ -420,6 +488,7 @@ async function readCredentials() {
     }
     const credentials = parsed;
     return {
+        account_id: stringValue(credentials.account_id),
         api_base_url: stringValue(credentials.api_base_url),
         api_key: stringValue(credentials.api_key),
         updated_at: stringValue(credentials.updated_at)
@@ -428,12 +497,15 @@ async function readCredentials() {
 async function saveCredentials(update) {
     const filePath = credentialsPath();
     const existing = (await readCredentials()) ?? {};
-    const sanitizedUpdate = Object.fromEntries(Object.entries(update).filter(([, value]) => value !== undefined));
+    const sanitizedUpdate = Object.fromEntries(Object.entries(update).filter(([, value]) => value !== undefined && value !== null));
     const credentials = {
         ...existing,
         ...sanitizedUpdate,
         updated_at: new Date().toISOString()
     };
+    if (update.account_id === null) {
+        delete credentials.account_id;
+    }
     const dir = path.dirname(filePath);
     await fs.mkdir(dir, { recursive: true, mode: 0o700 });
     await fs.chmod(dir, 0o700).catch(() => undefined);
@@ -706,6 +778,9 @@ function parseOptions(args) {
         else if (arg === "--message") {
             options.message = args[++index];
         }
+        else if (arg === "--account") {
+            options.account = args[++index];
+        }
         else {
             throw new Error(`Unknown option: ${arg}`);
         }
@@ -744,6 +819,9 @@ function parseSecretSetOptions(args) {
         if (arg === "--value") {
             options.value = args[++index];
         }
+        else if (arg === "--account") {
+            options.account = args[++index];
+        }
         else {
             throw new Error(`Unknown option: ${arg}`);
         }
@@ -766,6 +844,22 @@ function parseEventsOptions(args) {
         else if (arg === "--limit") {
             options.limit = args[++index];
         }
+        else if (arg === "--account") {
+            options.account = args[++index];
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}
+function parseAccountOptions(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--account") {
+            options.account = args[++index];
+        }
         else {
             throw new Error(`Unknown option: ${arg}`);
         }
@@ -879,32 +973,45 @@ function errorMessage(body) {
     }
     return message ?? code;
 }
+function isHelpCommand(command) {
+    return command === "--help" || command === "-h" || command === "help";
+}
 function usage(exitCode) {
-    console.error(`Usage:
+    const message = `Usage:
+  userland [--help]
   userland signup [--username <username>] [--password <password>] [--email <email>] [--no-save]
   userland login [--username <username>] [--password <password>] [--no-save]
   userland auth status
   userland auth save-key --username <username> --api-key <api-key> [--password <password>]
-  userland apps publish <dir> [--app <app-id>] [--message <message>]
-  userland apps list
-  userland apps releases <app-id>
-  userland apps rollback <app-id> <release-id>
-  userland apps secrets set <app-id> <NAME> [--value <value>]
-  userland apps events <app-id> [--type <event-type>] [--severity <level>] [--release <release-id>] [--limit <n>]
+  userland accounts list
+  userland accounts use <account-id>
+  userland apps publish <dir> [--app <app-id>] [--message <message>] [--account <account-id>]
+  userland apps list [--account <account-id>]
+  userland apps releases <app-id> [--account <account-id>]
+  userland apps rollback <app-id> <release-id> [--account <account-id>]
+  userland apps secrets set <app-id> <NAME> [--value <value>] [--account <account-id>]
+  userland apps events <app-id> [--type <event-type>] [--severity <level>] [--release <release-id>] [--limit <n>] [--account <account-id>]
 
 Aliases:
   userland auth signup [--username <username>] [--password <password>] [--email <email>] [--no-save]
   userland auth login [--username <username>] [--password <password>] [--no-save]
-  userland publish <dir> [--app <app-id>] [--message <message>]
-  userland releases <app-id>
+  userland publish <dir> [--app <app-id>] [--message <message>] [--account <account-id>]
+  userland releases <app-id> [--account <account-id>]
 
 Credentials:
   Commands use USERLAND_API_KEY first, then ~/.userland/credentials.json for API keys.
+  App commands use --account, then USERLAND_ACCOUNT_ID, then saved account_id when set.
   Account username and password are stored in the OS keychain.
 
 Docs:
   https://docs.userland.fun/reference/cli
-  https://docs.userland.fun/guides/troubleshooting`);
+  https://docs.userland.fun/guides/troubleshooting`;
+    if (exitCode === 0) {
+        console.log(message);
+    }
+    else {
+        console.error(message);
+    }
     process.exit(exitCode);
 }
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@userland.fun/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Userland command-line tools for publishing and operating apps.",
   "license": "MIT",
   "type": "module",