@eliya-oss/agent-slack 0.1.2 → 0.1.4

package/.agents/cli-api.md

@@ -38,8 +38,10 @@ Defaults:
 
 ```bash
 agent-slack auth login
+agent-slack auth login --token xoxb-... --scopes channels:read,channels:history,users:read
 agent-slack auth login --profile work --scopes channels:read,channels:history --user-scopes search:read.public,search:read.private
 agent-slack auth login --oauth --client-id CLIENT_ID --client-secret CLIENT_SECRET --auth-url-out /tmp/agent-slack-auth-url
+agent-slack auth login --oauth --client-id CLIENT_ID --client-secret CLIENT_SECRET --no-open
 agent-slack auth status
 agent-slack auth scopes
 agent-slack auth profiles list
@@ -48,8 +50,13 @@ agent-slack auth logout --profile work
 
 Auth behavior:
 
-- Uses Slack OAuth v2 with a localhost callback.
-- Bot scopes go in `scope=...`; user scopes go in `user_scope=...`.
+- Primary setup: `agent-slack auth login` uses the bundled Agent Slack public Client ID, opens Slack in the browser with PKCE, and stores a local user-token profile.
+- Users can also provide an existing Bot User OAuth Token with `--token`.
+- A normal user should not create a Slack app or provide client credentials.
+- Developer fallback: OAuth mode can use BYO Slack app credentials. The **Client ID** and **Client Secret** come from the Slack app's **Basic Information -> App Credentials** section.
+- OAuth opens the Slack OAuth URL in the default browser by default. Use `--no-open` to print the URL only, or `--auth-url-out PATH` for headless agents and tests.
+- PKCE uses `user_scope=...`; BYO OAuth bot scopes go in `scope=...`.
+- Default local callback: `http://localhost:45454/oauth/slack/callback`.
 - Stores profiles outside the project directory. The default store is `~/.config/agent-slack/profiles.json`; set `AGENT_SLACK_TOKEN_STORE=keychain` on macOS to keep token secrets in Keychain and only profile metadata on disk.
 - Supports multiple profiles and workspaces.
 - `auth status --json` returns token type, team, enterprise, user/bot identity, granted scopes, and missing recommended scopes.

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @eliya-oss/agent-slack
 
+## 0.1.4
+
+### Patch Changes
+
+- Add Slack PKCE browser login.
+
+  No-flag `auth login` now uses the bundled Agent Slack public Client ID with Slack OAuth PKCE for browser-based user-token login without a client secret. Token setup and BYO OAuth remain available for bot-token, development, and self-hosted workflows.
+
+## 0.1.3
+
+### Patch Changes
+
+- Open Slack OAuth login in the default browser by default.
+
+  Headless flows can still use `--auth-url-out PATH` or `--no-open`, and the CLI now reads its displayed version from package metadata so releases stay in sync.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -9,20 +9,45 @@ Short alias: `aslk`.
 npm install -g @eliya-oss/agent-slack
 ```
 
-<img src="./assets/terminal.svg" alt="Agent Slack terminal screenshot" width="820">
+<img src="./assets/terminal.webp" alt="Agent Slack terminal screenshot" width="820">
 
 </div>
 
 ## Usage
 
 ```bash
-agent-slack auth login --oauth --client-id "$SLACK_CLIENT_ID" --client-secret "$SLACK_CLIENT_SECRET" --json
+agent-slack auth login --json
 agent-slack conversation history C123 --limit 50 --json
 agent-slack thread get --channel C123 --ts 1710000000.000100 --include users,permalinks --json
 agent-slack conversation context C123 --include users,threads,permalinks --format ndjson
 agent-slack api call conversations.info --payload '{"channel":"C123"}' --json
 ```
 
+## Auth
+
+Browser login:
+
+```bash
+agent-slack auth login
+```
+
+Agent Slack opens Slack in the browser with PKCE and stores a local user-token profile. Users do not create Slack apps or handle Slack client secrets.
+
+Token setup:
+
+```bash
+agent-slack auth login --token "$SLACK_BOT_TOKEN" --scopes channels:read,channels:history,users:read
+```
+
+Developer/self-hosted fallback:
+
+1. Create a Slack app at <https://api.slack.com/apps>.
+2. Add the needed scopes under **OAuth & Permissions**.
+3. Install it to your workspace and copy the **Bot User OAuth Token**.
+4. Run `agent-slack auth login --token "$SLACK_BOT_TOKEN" --scopes ...`.
+
+OAuth with `--client-id` and `--client-secret` is only for bring-your-own-app development and self-hosted setups.
+
 ## Skill
 
 ```bash

package/dist/adapters/localhost-oauth/NodeLocalhostOAuthFlow.js

@@ -1,4 +1,5 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
 import { writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { PermissionDenied, SlackApiFailed, UsageError } from "../../domain/errors.js";
@@ -12,22 +13,26 @@ export class NodeLocalhostOAuthFlow {
         const apiBaseUrl = env.AGENT_SLACK_API_BASE_URL ?? env.SLK_SLACK_API_BASE_URL;
         const emulatorBaseUrl = apiBaseUrl?.replace(/\/api\/?$/, "");
         const redirectHost = env.AGENT_SLACK_OAUTH_REDIRECT_HOST ?? env.SLK_OAUTH_REDIRECT_HOST;
+        const redirectPort = env.AGENT_SLACK_OAUTH_REDIRECT_PORT ?? env.SLK_OAUTH_REDIRECT_PORT;
         const redirectPath = env.AGENT_SLACK_OAUTH_REDIRECT_PATH ?? env.SLK_OAUTH_REDIRECT_PATH;
         const timeoutMs = env.AGENT_SLACK_OAUTH_TIMEOUT_MS ?? env.SLK_OAUTH_TIMEOUT_MS;
         return new NodeLocalhostOAuthFlow({
             authorizeUrl: env.AGENT_SLACK_OAUTH_AUTHORIZE_URL ?? env.SLK_SLACK_OAUTH_AUTHORIZE_URL ?? (emulatorBaseUrl === undefined ? "https://slack.com/oauth/v2/authorize" : `${emulatorBaseUrl}/oauth/v2/authorize`),
             tokenUrl: env.AGENT_SLACK_OAUTH_ACCESS_URL ?? env.SLK_SLACK_OAUTH_ACCESS_URL ?? (apiBaseUrl === undefined ? "https://slack.com/api/oauth.v2.access" : `${apiBaseUrl.replace(/\/?$/, "/")}oauth.v2.access`),
             ...(redirectHost === undefined ? {} : { defaultRedirectHost: redirectHost }),
+            ...(redirectPort === undefined ? {} : { defaultRedirectPort: Number(redirectPort) }),
             ...(redirectPath === undefined ? {} : { defaultRedirectPath: redirectPath }),
             ...(timeoutMs === undefined ? {} : { defaultTimeoutMs: Number(timeoutMs) })
         });
     }
     async login(input) {
         const state = randomBytes(24).toString("base64url");
+        const codeVerifier = input.pkce === true ? randomBytes(32).toString("base64url") : undefined;
         const timeoutMs = input.timeoutMs ?? this.options.defaultTimeoutMs ?? 120_000;
         const server = createServer();
         const started = await listen(server, input.redirectUri, {
-            host: this.options.defaultRedirectHost ?? "127.0.0.1",
+            host: this.options.defaultRedirectHost ?? defaultRedirectHost,
+            port: this.options.defaultRedirectPort ?? defaultRedirectPort,
             path: this.options.defaultRedirectPath ?? "/oauth/slack/callback"
         });
         const authorizationUrl = buildAuthorizationUrl({
@@ -36,11 +41,18 @@ export class NodeLocalhostOAuthFlow {
             redirectUri: started.redirectUri,
             scopes: input.scopes,
             userScopes: input.userScopes,
-            state
+            state,
+            ...(codeVerifier === undefined ? {} : { codeChallenge: codeChallengeFor(codeVerifier) })
         });
         if (input.authUrlOut !== undefined) {
             await writeFile(input.authUrlOut, authorizationUrl, "utf8");
         }
+        else if (input.openBrowser !== false) {
+            const opened = await (this.options.openBrowser ?? openSystemBrowser)(authorizationUrl);
+            process.stderr.write(opened
+                ? `Opening Slack OAuth in your browser.\nIf it did not open, visit:\n${authorizationUrl}\n`
+                : `Could not open a browser automatically. Visit this Slack OAuth URL:\n${authorizationUrl}\n`);
+        }
         else {
             process.stderr.write(`Open this Slack OAuth URL:\n${authorizationUrl}\n`);
         }
@@ -72,9 +84,10 @@ export class NodeLocalhostOAuthFlow {
                         code,
                         clientId: input.clientId,
                         clientSecret: input.clientSecret,
+                        codeVerifier,
                         redirectUri: started.redirectUri
                     });
-                    const profile = toAuthProfile(input.profileName, access);
+                    const profile = toAuthProfile(input.profileName, access, input.pkce === true ? "user" : "bot");
                     response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end("<html><body>Slack auth complete. You can close this tab.</body></html>");
                     clearTimeout(timer);
                     closeServer(server);
@@ -94,7 +107,7 @@ const listen = (server, redirectUri, fallback) => new Promise((resolve, reject)
     const parsed = redirectUri === undefined ? null : new URL(redirectUri);
     const host = parsed?.hostname ?? fallback.host;
     const path = parsed?.pathname ?? fallback.path;
-    const port = parsed === null || parsed.port === "" ? 0 : Number(parsed.port);
+    const port = parsed === null || parsed.port === "" ? fallback.port : Number(parsed.port);
     if (!Number.isInteger(port) || port < 0) {
         reject(new UsageError("OAuth redirect URI must include a valid port", { redirectUri }));
         return;
@@ -102,34 +115,48 @@ const listen = (server, redirectUri, fallback) => new Promise((resolve, reject)
     server.once("error", reject);
     server.listen(port, host, () => {
         const address = server.address();
-        const actualPort = parsed === null || parsed.port === "" ? address.port : port;
+        const actualPort = parsed === null || parsed.port === "" ? port : address.port;
         resolve({
             redirectUri: redirectUri ?? `http://${host}:${actualPort}${path}`,
             path
         });
     });
 });
+const defaultRedirectHost = "localhost";
+const defaultRedirectPort = 45454;
 const buildAuthorizationUrl = (input) => {
     const url = new URL(input.authorizeUrl);
     url.searchParams.set("client_id", input.clientId);
-    url.searchParams.set("scope", input.scopes.join(","));
+    if (input.scopes.length > 0) {
+        url.searchParams.set("scope", input.scopes.join(","));
+    }
     if (input.userScopes.length > 0) {
         url.searchParams.set("user_scope", input.userScopes.join(","));
     }
     url.searchParams.set("redirect_uri", input.redirectUri);
     url.searchParams.set("state", input.state);
+    if (input.codeChallenge !== undefined) {
+        url.searchParams.set("code_challenge", input.codeChallenge);
+        url.searchParams.set("code_challenge_method", "S256");
+    }
     return url.toString();
 };
 const exchangeCode = async (input) => {
+    const requestBody = new URLSearchParams({
+        code: input.code,
+        client_id: input.clientId,
+        redirect_uri: input.redirectUri
+    });
+    if (input.clientSecret !== undefined) {
+        requestBody.set("client_secret", input.clientSecret);
+    }
+    if (input.codeVerifier !== undefined) {
+        requestBody.set("code_verifier", input.codeVerifier);
+    }
     const response = await fetch(input.tokenUrl, {
         method: "POST",
         headers: { "content-type": "application/x-www-form-urlencoded" },
-        body: new URLSearchParams({
-            code: input.code,
-            client_id: input.clientId,
-            client_secret: input.clientSecret,
-            redirect_uri: input.redirectUri
-        })
+        body: requestBody
     });
     const body = await response.json();
     if (body.ok === false) {
@@ -142,22 +169,48 @@ const exchangeCode = async (input) => {
     }
     return body;
 };
-const toAuthProfile = (profileName, response) => {
+const toAuthProfile = (profileName, response, preferredTokenType) => {
     const botScopes = splitScopes(response.scope);
     const userScopes = splitScopes(response.authed_user?.scope);
+    const rootTokenIsUser = preferredTokenType === "user" && response.access_token !== undefined && response.token_type !== "bot";
+    const userToken = response.authed_user?.access_token ?? (rootTokenIsUser ? response.access_token : undefined);
+    const useUserToken = preferredTokenType === "user" && userToken !== undefined;
+    const scopes = useUserToken && userScopes.length > 0 ? userScopes : [...botScopes, ...userScopes];
     return {
         name: ProfileName.make(profileName),
-        tokenType: response.access_token === undefined ? "user" : "bot",
+        tokenType: useUserToken || response.access_token === undefined ? "user" : "bot",
         enterpriseId: response.enterprise?.id ?? null,
         ...(response.team?.id === undefined ? {} : { teamId: response.team.id }),
         ...(response.authed_user?.id === undefined ? {} : { userId: response.authed_user.id }),
         ...(response.bot_user_id === undefined ? {} : { botId: response.bot_user_id }),
-        ...(response.access_token === undefined ? {} : { botToken: response.access_token }),
-        ...(response.authed_user?.access_token === undefined ? {} : { userToken: response.authed_user.access_token }),
-        scopes: [...new Set([...botScopes, ...userScopes])].map(Scope.make)
+        ...(response.access_token === undefined || useUserToken ? {} : { botToken: response.access_token }),
+        ...(userToken === undefined ? {} : { userToken }),
+        scopes: [...new Set(scopes)].map(Scope.make)
     };
 };
+const codeChallengeFor = (codeVerifier) => createHash("sha256").update(codeVerifier).digest("base64url");
 const splitScopes = (value) => value === undefined || value.trim() === "" ? [] : value.split(",").map((scope) => scope.trim()).filter(Boolean);
 const closeServer = (server) => {
     server.close();
 };
+const openSystemBrowser = (url) => new Promise((resolve) => {
+    const command = browserCommand(url);
+    const child = spawn(command.file, command.args, {
+        detached: true,
+        stdio: "ignore"
+    });
+    child.once("error", () => resolve(false));
+    child.once("spawn", () => {
+        child.unref();
+        resolve(true);
+    });
+});
+const browserCommand = (url) => {
+    if (process.platform === "darwin") {
+        return { file: "open", args: [url] };
+    }
+    if (process.platform === "win32") {
+        return { file: "cmd", args: ["/c", "start", "", url] };
+    }
+    return { file: "xdg-open", args: [url] };
+};

package/dist/application/commands.js

@@ -1,6 +1,6 @@
 import { flagBoolean, flagString, requireFlag, splitCsv } from "../cli/args.js";
 import { PRIMARY_COMMAND_NAME, describeAllCommands, describeCommandGroup, findCommandMetadata, renderCompletion, renderHumanHelp } from "../cli/metadata.js";
-import { NotAuthenticated, ResourceNotFound, UnsupportedMethod, UsageError } from "../domain/errors.js";
+import { ResourceNotFound, UnsupportedMethod, UsageError } from "../domain/errors.js";
 import { ProfileName, Scope } from "../domain/ids.js";
 import { pagingFrom, successEnvelope, toNdjson } from "../output/envelope.js";
 import { renderHumanEnvelope } from "../output/human.js";
@@ -196,21 +196,27 @@ const authCommand = async (parsed, services) => {
             await services.tokenStore.setProfile(profile);
             return { method: "auth.login", profile, stdoutValue: sanitizeProfile(profile) };
         }
-        const clientId = flagString(parsed, "client-id") ?? process.env.AGENT_SLACK_CLIENT_ID ?? process.env.SLK_CLIENT_ID ?? process.env.SLACK_CLIENT_ID;
+        const clientId = flagString(parsed, "client-id") ?? process.env.AGENT_SLACK_CLIENT_ID ?? process.env.AGENT_SLACK_PUBLIC_CLIENT_ID ?? process.env.SLK_CLIENT_ID ?? process.env.SLACK_CLIENT_ID ?? defaultPkceClientId;
         const clientSecret = flagString(parsed, "client-secret") ?? process.env.AGENT_SLACK_CLIENT_SECRET ?? process.env.SLK_CLIENT_SECRET ?? process.env.SLACK_CLIENT_SECRET;
-        if (clientId === undefined || clientSecret === undefined) {
-            throw new NotAuthenticated("OAuth login needs --client-id/--client-secret or AGENT_SLACK_CLIENT_ID/AGENT_SLACK_CLIENT_SECRET");
+        const byoOAuth = flagBoolean(parsed, "oauth");
+        if (byoOAuth && (clientId === undefined || clientSecret === undefined)) {
+            throw new UsageError("BYO Slack OAuth needs both --client-id and --client-secret.", {
+                suggestion: "Use --token with an existing Bot User OAuth Token, or pass both BYO Slack app credentials from Basic Information -> App Credentials."
+            });
         }
         const scopes = splitCsv(flagString(parsed, "scopes"));
+        const userScopes = splitCsv(flagString(parsed, "user-scopes"));
+        const pkceUserScopes = userScopes.length > 0 ? userScopes : scopes.length > 0 ? scopes : defaultPkceUserScopes;
         const profile = await services.oauthFlow.login({
             profileName,
             clientId,
-            clientSecret,
-            scopes: scopes.length === 0 ? defaultOAuthScopes : scopes,
-            userScopes: splitCsv(flagString(parsed, "user-scopes")),
+            ...(byoOAuth ? { clientSecret } : { pkce: true }),
+            scopes: byoOAuth ? (scopes.length === 0 ? defaultOAuthScopes : scopes) : [],
+            userScopes: byoOAuth ? userScopes : pkceUserScopes,
             redirectUri: flagString(parsed, "redirect-uri"),
             authUrlOut: flagString(parsed, "auth-url-out"),
-            timeoutMs: numberFlag(parsed, "timeout-ms")
+            timeoutMs: numberFlag(parsed, "timeout-ms"),
+            openBrowser: !flagBoolean(parsed, "no-open")
         });
         await services.tokenStore.setProfile(profile);
         return { method: "auth.login", profile, stdoutValue: sanitizeProfile(profile) };
@@ -233,6 +239,8 @@ const defaultOAuthScopes = [
     "bookmarks:read",
     "team:read"
 ];
+const defaultPkceUserScopes = defaultOAuthScopes;
+const defaultPkceClientId = "8263309029475.11499738391475";
 const apiCall = async (parsed, services) => {
     const method = requirePositional(parsed.positionals, 2, "METHOD");
     const payload = await parseJsonPayload({

package/dist/application/execute.js

@@ -1,9 +1,11 @@
-import { parseArgs } from "../cli/args.js";
+import { flagBoolean, flagString, parseArgs } from "../cli/args.js";
 import { errorEnvelope } from "../output/envelope.js";
+import { renderHumanErrorEnvelope } from "../output/human.js";
 import { dispatch, renderDispatchResult } from "./commands.js";
 export const executeCli = async (argv, services, options = {}) => {
+    let parsed = null;
     try {
-        const parsed = parseArgs(argv);
+        parsed = parseArgs(argv);
         const result = await dispatch(parsed, services);
         return {
             exitCode: 0,
@@ -13,10 +15,21 @@ export const executeCli = async (argv, services, options = {}) => {
     }
     catch (error) {
         const { envelope, exitCode } = errorEnvelope(error);
+        const stderr = shouldRenderJsonError(argv, parsed, options)
+            ? `${JSON.stringify(envelope, null, 2)}\n`
+            : renderHumanErrorEnvelope(envelope, {
+                color: shouldColorError(argv, parsed, options)
+            });
         return {
             exitCode,
             stdout: "",
-            stderr: `${JSON.stringify(envelope, null, 2)}\n`
+            stderr
         };
     }
 };
+const shouldRenderJsonError = (argv, parsed, options) => parsed === null
+    ? argv.includes("--json") || options.stdoutIsTty !== true
+    : flagBoolean(parsed, "json") || flagString(parsed, "format") === "json" || options.stdoutIsTty !== true;
+const shouldColorError = (argv, parsed, options) => options.stdoutIsTty === true &&
+    options.env?.NO_COLOR === undefined &&
+    (parsed === null ? !argv.includes("--no-color") : !flagBoolean(parsed, "no-color"));

package/dist/cli/args.js

@@ -10,7 +10,8 @@ const booleanFlags = new Set([
     "yes",
     "no-cache",
     "inclusive",
-    "oauth"
+    "oauth",
+    "no-open"
 ]);
 export const parseArgs = (argv) => {
     const flags = new Map();

package/dist/cli/metadata.js

@@ -1,7 +1,10 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../../package.json");
 export const PRIMARY_COMMAND_NAME = "agent-slack";
 export const SHORT_COMMAND_NAME = "aslk";
 export const COMMAND_NAMES = [PRIMARY_COMMAND_NAME, SHORT_COMMAND_NAME];
-export const CLI_VERSION = "0.1.2";
+export const CLI_VERSION = packageJson.version ?? "0.0.0";
 export const commandMetadata = [
     {
         path: ["describe"],
@@ -29,13 +32,14 @@ export const commandMetadata = [
     },
     {
         path: ["auth", "login"],
-        summary: "Create a Slack auth profile with OAuth or a seeded token.",
-        flags: ["--profile", "--oauth", "--client-id", "--client-secret", "--scopes", "--user-scopes", "--redirect-uri", "--auth-url-out", "--timeout-ms", "--token", "--json"],
+        summary: "Connect a Slack workspace profile.",
+        flags: ["--profile", "--oauth", "--client-id", "--client-secret", "--scopes", "--user-scopes", "--redirect-uri", "--auth-url-out", "--timeout-ms", "--no-open", "--token", "--json"],
         safety: "read",
         output: "profile status",
         examples: [
+            "agent-slack auth login --json",
+            "AGENT_SLACK_TOKEN=xoxb-... agent-slack auth login --profile work --scopes channels:read --json",
             "agent-slack auth login --oauth --client-id 123.456 --client-secret secret --scopes channels:read,channels:history --json",
-            "AGENT_SLACK_TOKEN=xoxb-... agent-slack auth login --profile work --scopes channels:read --json"
         ]
     },
     {
@@ -287,6 +291,9 @@ export const describeCommandGroup = (group) => ({
     commands: commandMetadata.filter((command) => command.path[0] === group)
 });
 export const renderHumanHelp = (path) => {
+    if (path.join(" ") === "auth login") {
+        return renderAuthLoginHelp();
+    }
     const command = findCommandMetadata(path);
     if (command !== null) {
         return [
@@ -294,11 +301,8 @@ export const renderHumanHelp = (path) => {
             "",
             command.summary,
             "",
-            command.args === undefined ? "" : `Arguments: ${command.args.join(" ")}`,
-            command.flags === undefined ? "" : `Flags: ${command.flags.join(", ")}`,
+            command.args === undefined ? "" : `Usage: ${PRIMARY_COMMAND_NAME} ${command.path.join(" ")} ${command.args.join(" ")}`,
             command.scopes === undefined ? "" : `Scopes: ${command.scopes.join(", ")}`,
-            `Safety: ${command.safety}`,
-            `Output: ${command.output}`,
             "",
             "Examples:",
             ...command.examples.map((example) => `  ${example}`)
@@ -314,6 +318,42 @@ export const renderHumanHelp = (path) => {
         ...commands.map((item) => `  ${item.path.join(" ").padEnd(28)} ${item.summary}`)
     ].join("\n") + "\n";
 };
+const renderAuthLoginHelp = () => [
+    "agent-slack auth login",
+    "",
+    "Connect a Slack workspace profile.",
+    "",
+    "Browser login",
+    "  agent-slack auth login",
+    "",
+    "  Opens Slack in the browser with PKCE and stores a local user-token profile.",
+    "  No Slack app secret is stored in the CLI.",
+    "",
+    "Token setup",
+    "  agent-slack auth login --token \"$SLACK_BOT_TOKEN\" --scopes channels:read,channels:history,users:read",
+    "",
+    "  Stores an existing Slack Bot User OAuth Token as a local profile.",
+    "",
+    "Developer fallback: bring your own Slack app OAuth credentials",
+    "  agent-slack auth login --oauth --client-id \"$SLACK_CLIENT_ID\" --client-secret \"$SLACK_CLIENT_SECRET\"",
+    "",
+    "Options",
+    "  --profile NAME          Save as a named profile.",
+    "  --token TOKEN           Store an existing Bot User OAuth Token.",
+    "  --scopes LIST           Token scopes, or PKCE user scopes when --oauth is not used.",
+    "  --user-scopes LIST      Explicit Slack user scopes for OAuth.",
+    "  --oauth                 Use Slack OAuth with BYO app credentials.",
+    "  --client-id VALUE       Override the Slack app Client ID.",
+    "  --client-secret VALUE   Slack app Client Secret.",
+    "  --no-open               Print OAuth URL instead of opening the browser.",
+    "  --auth-url-out PATH     Write OAuth URL for headless flows.",
+    "  --json                  Emit a parseable JSON envelope.",
+    "",
+    "Notes",
+    "  Normal users should not create a Slack app or handle client credentials.",
+    "  BYO OAuth credentials are only for development and self-hosted setups.",
+    ""
+].join("\n");
 export const renderCompletion = (shell) => {
     const words = [...new Set(commandMetadata.flatMap((command) => command.path))];
     const commandWords = commandMetadata.map((command) => command.path.join(" "));

package/dist/output/envelope.js

@@ -22,10 +22,12 @@ export const successEnvelope = (input) => ({
 });
 export const errorEnvelope = (error) => {
     const normalized = normalizeUnknownError(error);
-    const detailsSlackError = typeof normalized.details.slackError === "string" ? normalized.details.slackError : undefined;
+    const details = Object.fromEntries(Object.entries(normalized.details).filter(([key]) => key !== "suggestion"));
+    const detailsSlackError = typeof details.slackError === "string" ? details.slackError : undefined;
     const slackError = "slackError" in normalized ? normalized.slackError ?? detailsSlackError : detailsSlackError;
     const retryAfterSeconds = "retryAfterSeconds" in normalized ? normalized.retryAfterSeconds : undefined;
-    const suggestion = suggestionFor(normalized._tag);
+    const detailSuggestion = typeof normalized.details.suggestion === "string" ? normalized.details.suggestion : undefined;
+    const suggestion = detailSuggestion ?? suggestionFor(normalized._tag);
     const envelope = {
         ok: false,
         error: {
@@ -36,7 +38,7 @@ export const errorEnvelope = (error) => {
             ...(retryAfterSeconds === undefined ? {} : { retry_after_seconds: retryAfterSeconds }),
             ...(suggestion === undefined ? {} : { suggestion }),
             trace_id: `slk_${randomUUID()}`,
-            ...(Object.keys(normalized.details).length === 0 ? {} : { details: normalized.details })
+            ...(Object.keys(details).length === 0 ? {} : { details })
         }
     };
     return { envelope, exitCode: normalized.exitCode };

package/dist/output/human.js

@@ -3,6 +3,7 @@ const codes = {
     cyan: [36, 39],
     dim: [2, 22],
     green: [32, 39],
+    red: [31, 39],
     yellow: [33, 39]
 };
 export const renderHumanEnvelope = (envelope, options) => {
@@ -21,6 +22,20 @@ export const renderHumanEnvelope = (envelope, options) => {
     ];
     return `${lines.join("\n")}\n`;
 };
+export const renderHumanErrorEnvelope = (envelope, options) => {
+    const paint = (name, value) => options.color ? `\u001b[${codes[name][0]}m${value}\u001b[${codes[name][1]}m` : value;
+    const error = envelope.error;
+    const lines = [
+        `${paint("red", "Error")} ${paint("bold", error.type)}`,
+        error.title,
+        ...(error.slack_error === undefined ? [] : ["", `${paint("dim", "Slack")} ${error.slack_error}`]),
+        ...(error.retry_after_seconds === undefined ? [] : [`${paint("dim", "Retry after")} ${error.retry_after_seconds}s`]),
+        ...(error.suggestion === undefined ? [] : ["", paint("yellow", "Next"), `  ${error.suggestion}`]),
+        "",
+        `${paint("dim", "Trace")} ${error.trace_id}`
+    ];
+    return `${lines.join("\n")}\n`;
+};
 const isCommandCatalog = (value) => {
     if (!isRecord(value) || typeof value.name !== "string" || !Array.isArray(value.commands)) {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eliya-oss/agent-slack",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Slack context CLI for AI agents.",
   "type": "module",
   "packageManager": "pnpm@11.9.0",

package/skills/agent-slack/SKILL.md

@@ -11,11 +11,41 @@ Use `agent-slack` as the Slack context boundary. `aslk` is the short alias. Pref
 
 1. Check availability: `agent-slack describe --json`.
 2. Check auth: `agent-slack auth status --json`.
-3. If auth is missing, ask the user to run OAuth or provide a seeded profile; do not invent credentials.
+3. If auth is missing, ask the user to run `agent-slack auth login`. It opens Slack in the browser with PKCE and stores a local user-token profile.
 4. Use specific read commands before raw API calls.
 5. Use `--json` for bounded results and `--format ndjson` for large context streams.
 6. Read structured errors from stderr; do not parse progress text from stdout.
 
+## Onboarding
+
+Browser login:
+
+```bash
+agent-slack auth login
+```
+
+Agent Slack opens Slack in the browser with PKCE and stores a local user-token profile. Users should not create a Slack app or handle `client-id`/`client-secret`.
+
+Token setup:
+
+```bash
+agent-slack auth login --token "$SLACK_BOT_TOKEN" --scopes channels:read,channels:history,users:read --json
+```
+
+This stores an existing Slack Bot User OAuth Token as a local profile.
+
+Developer/self-hosted fallback:
+
+1. Create or open a Slack app at https://api.slack.com/apps.
+2. Go to **OAuth & Permissions**, add the needed bot scopes, install the app to the workspace, and copy the **Bot User OAuth Token**.
+3. For OAuth auth, get the **Client ID** and **Client Secret** from **Basic Information -> App Credentials** in that Slack app, then run:
+
+```bash
+agent-slack auth login --oauth --client-id "$SLACK_CLIENT_ID" --client-secret "$SLACK_CLIENT_SECRET" --json
+```
+
+Treat Slack app creation and client credentials as an advanced developer fallback only.
+
 ## Common Commands
 
 ```bash

package/assets/terminal.svg

@@ -1,32 +0,0 @@
-<svg width="980" height="560" viewBox="0 0 980 560" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
-  <title id="title">Agent Slack terminal screenshot</title>
-  <desc id="desc">A terminal showing Agent Slack commands that read Slack context as JSON and NDJSON.</desc>
-  <rect width="980" height="560" rx="18" fill="#111827"/>
-  <rect x="22" y="22" width="936" height="516" rx="14" fill="#0B1020" stroke="#263244"/>
-  <rect x="22" y="22" width="936" height="48" rx="14" fill="#151D2E"/>
-  <circle cx="52" cy="46" r="7" fill="#FF5F57"/>
-  <circle cx="76" cy="46" r="7" fill="#FFBD2E"/>
-  <circle cx="100" cy="46" r="7" fill="#28C840"/>
-  <text x="490" y="51" text-anchor="middle" fill="#94A3B8" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">agent-slack</text>
-
-  <text x="54" y="116" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
-  <text x="78" y="116" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">npm install -g @eliya-oss/agent-slack</text>
-
-  <text x="54" y="162" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
-  <text x="78" y="162" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">aslk auth status</text>
-  <text x="78" y="196" fill="#86EFAC" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">ok auth.status  profile work | team T123</text>
-
-  <text x="54" y="250" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
-  <text x="78" y="250" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">aslk conversation history C123 --limit 3</text>
-  <text x="78" y="284" fill="#FDE68A" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">ts                   user  text</text>
-  <text x="78" y="314" fill="#FDE68A" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">1710000000.000100   U123  Ship status?</text>
-
-  <text x="54" y="368" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
-  <text x="78" y="368" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">agent-slack thread get --channel C123 --ts 1710000000.000100 --include users --json</text>
-  <text x="78" y="402" fill="#C4B5FD" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{ "ok": true, "method": "conversations.replies", "data": { "messages": [ ... ] } }</text>
-
-  <text x="54" y="456" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
-  <text x="78" y="456" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">agent-slack api call conversations.info --payload '{"channel":"C123"}' --json</text>
-  <rect x="54" y="488" width="210" height="28" rx="6" fill="#122034"/>
-  <text x="70" y="508" fill="#67E8F9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">--json stays parseable</text>
-</svg>