@eliya-oss/agent-slack 0.1.0 → 0.1.1

package/.agents/cli-api.md

@@ -2,7 +2,7 @@
 
 Technical contract derived from `.agents/prd/001-agent-readable-slack-interface.md`. Product behavior changes belong in PRD first.
 
-Working binary name: `slk`.
+Working binary name: `agent-slack`. Short alias: `aslk`.
 
 Goal: OAuth into Slack, expose everything Slack Web API permissions allow, and give agents stable commands for reading channels, threads, files, users, and search context.
 
@@ -10,18 +10,18 @@ Non-goal for v0: agent-side summarization. The CLI returns clean context; agents
 
 ## Design Rules
 
-- Noun-verb commands: `slk conversation history`, `slk thread get`, `slk api call`.
+- Noun-verb commands: `agent-slack conversation history`, `agent-slack thread get`, `agent-slack api call`.
 - JSON is always available with `--json`; non-TTY stdout defaults to JSON.
 - Data goes to stdout. Progress, warnings, and errors go to stderr.
 - Every command supports `--help --json`; every group supports `describe --json`.
 - Large reads support `--cursor`, `--limit`, `--all`, and `--format ndjson`.
-- Raw Slack Web API access is first-class through `slk api call`.
+- Raw Slack Web API access is first-class through `agent-slack api call`.
 - Read commands are safe by default. Any future write/destructive command needs `--yes`; `api call` blocks known write methods unless `--allow-write`.
 
 ## Global Flags
 
 ```bash
-slk [--profile NAME] [--team TEAM_ID] [--token user|bot|admin|app]
+agent-slack [--profile NAME] [--team TEAM_ID] [--token user|bot|admin|app]
     [--json] [--format json|ndjson|table] [--fields FIELD[,FIELD...]]
     [--limit N] [--cursor CURSOR] [--all]
     [--include users,reactions,files,permalinks,threads]
@@ -37,30 +37,30 @@ Defaults:
 ## Auth
 
 ```bash
-slk auth login
-slk auth login --profile work --scopes channels:read,channels:history --user-scopes search:read.public,search:read.private
-slk auth login --oauth --client-id CLIENT_ID --client-secret CLIENT_SECRET --auth-url-out /tmp/slk-auth-url
-slk auth status
-slk auth scopes
-slk auth profiles list
-slk auth logout --profile work
+agent-slack auth login
+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 status
+agent-slack auth scopes
+agent-slack auth profiles list
+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=...`.
-- Stores profiles outside the project directory. The default store is `~/.config/slk/profiles.json`; set `SLK_TOKEN_STORE=keychain` on macOS to keep token secrets in Keychain and only profile metadata on disk.
+- 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.
 
 Scope presets:
 
 ```bash
-slk auth login --preset read-user
-slk auth login --preset read-bot
-slk auth login --preset assistant-search
-slk auth login --preset admin-read
+agent-slack auth login --preset read-user
+agent-slack auth login --preset read-bot
+agent-slack auth login --preset assistant-search
+agent-slack auth login --preset admin-read
 ```
 
 Preset intent:
@@ -77,31 +77,31 @@ Important Slack boundary: there is no token that means "read all Slack." Slack o
 ### Workspaces and identity
 
 ```bash
-slk auth test
-slk team get
-slk team profile get
-slk enterprise get
+agent-slack auth test
+agent-slack team get
+agent-slack team profile get
+agent-slack enterprise get
 ```
 
 ### Users
 
 ```bash
-slk user list [--all]
-slk user get USER_ID
-slk user lookup --email EMAIL
-slk user presence get USER_ID
-slk usergroups list
-slk usergroups users list USERGROUP_ID
+agent-slack user list [--all]
+agent-slack user get USER_ID
+agent-slack user lookup --email EMAIL
+agent-slack user presence get USER_ID
+agent-slack usergroups list
+agent-slack usergroups users list USERGROUP_ID
 ```
 
 ### Conversations
 
 ```bash
-slk conversation list --types public_channel,private_channel,mpim,im [--all]
-slk conversation get CHANNEL_ID
-slk conversation members CHANNEL_ID [--all]
-slk conversation history CHANNEL_ID [--oldest TS] [--latest TS] [--all]
-slk conversation context CHANNEL_ID [--since 24h] [--include users,reactions,files,threads]
+agent-slack conversation list --types public_channel,private_channel,mpim,im [--all]
+agent-slack conversation get CHANNEL_ID
+agent-slack conversation members CHANNEL_ID [--all]
+agent-slack conversation history CHANNEL_ID [--oldest TS] [--latest TS] [--all]
+agent-slack conversation context CHANNEL_ID [--since 24h] [--include users,reactions,files,threads]
 ```
 
 `conversation context` is the agent-friendly form: normalized messages, hydrated users, thread refs, file refs, reactions, and permalinks in one deterministic payload.
@@ -109,9 +109,9 @@ slk conversation context CHANNEL_ID [--since 24h] [--include users,reactions,fil
 ### Threads and messages
 
 ```bash
-slk thread get --channel CHANNEL_ID --ts MESSAGE_TS [--include users,reactions,files,permalinks]
-slk message get --channel CHANNEL_ID --ts MESSAGE_TS
-slk message permalink --channel CHANNEL_ID --ts MESSAGE_TS
+agent-slack thread get --channel CHANNEL_ID --ts MESSAGE_TS [--include users,reactions,files,permalinks]
+agent-slack message get --channel CHANNEL_ID --ts MESSAGE_TS
+agent-slack message permalink --channel CHANNEL_ID --ts MESSAGE_TS
 ```
 
 `message get` wraps the Slack history/replies calls needed to fetch one timestamp.
@@ -119,9 +119,9 @@ slk message permalink --channel CHANNEL_ID --ts MESSAGE_TS
 ### Search
 
 ```bash
-slk search context --query QUERY [--channel-types public_channel,private_channel,mpim,im] [--content-types messages,files,channels]
-slk search messages --query QUERY
-slk search files --query QUERY
+agent-slack search context --query QUERY [--channel-types public_channel,private_channel,mpim,im] [--content-types messages,files,channels]
+agent-slack search messages --query QUERY
+agent-slack search files --query QUERY
 ```
 
 Prefer `search context` for agents. It maps to Slack's Real-time Search API where available. `search messages` and `search files` are legacy-compatible convenience commands.
@@ -129,26 +129,26 @@ Prefer `search context` for agents. It maps to Slack's Real-time Search API wher
 ### Files and attached context
 
 ```bash
-slk file list [--channel CHANNEL_ID] [--user USER_ID] [--all]
-slk file get FILE_ID
-slk file download FILE_ID --out PATH
-slk file comments list FILE_ID
+agent-slack file list [--channel CHANNEL_ID] [--user USER_ID] [--all]
+agent-slack file get FILE_ID
+agent-slack file download FILE_ID --out PATH
+agent-slack file comments list FILE_ID
 ```
 
 ### Other readable Slack surfaces
 
 ```bash
-slk reaction get --channel CHANNEL_ID --ts MESSAGE_TS
-slk pin list CHANNEL_ID
-slk bookmark list CHANNEL_ID
-slk canvas list [--channel CHANNEL_ID]
-slk canvas get CANVAS_ID
-slk list list [--channel CHANNEL_ID]
-slk list get LIST_ID
-slk emoji list
-slk reminder list
-slk star list
-slk dnd status [USER_ID]
+agent-slack reaction get --channel CHANNEL_ID --ts MESSAGE_TS
+agent-slack pin list CHANNEL_ID
+agent-slack bookmark list CHANNEL_ID
+agent-slack canvas list [--channel CHANNEL_ID]
+agent-slack canvas get CANVAS_ID
+agent-slack list list [--channel CHANNEL_ID]
+agent-slack list get LIST_ID
+agent-slack emoji list
+agent-slack reminder list
+agent-slack star list
+agent-slack dnd status [USER_ID]
 ```
 
 ## Generic Web API Escape Hatch
@@ -156,11 +156,11 @@ slk dnd status [USER_ID]
 This is what gives full Web API coverage.
 
 ```bash
-slk api methods list [--family conversations]
-slk api method describe conversations.history
-slk api call conversations.history --payload '{"channel":"C123","limit":50}'
-slk api call conversations.history --payload @payload.json
-cat payload.json | slk api call conversations.history -
+agent-slack api methods list [--family conversations]
+agent-slack api method describe conversations.history
+agent-slack api call conversations.history --payload '{"channel":"C123","limit":50}'
+agent-slack api call conversations.history --payload @payload.json
+cat payload.json | agent-slack api call conversations.history -
 ```
 
 Rules:
@@ -235,10 +235,10 @@ Rate-limit behavior:
 ## Schema Introspection
 
 ```bash
-slk describe --json
-slk conversation describe --json
-slk conversation history --help --json
-slk api method describe conversations.replies --json
+agent-slack describe --json
+agent-slack conversation describe --json
+agent-slack conversation history --help --json
+agent-slack api method describe conversations.replies --json
 ```
 
 Schema output includes:
@@ -256,25 +256,25 @@ Schema output includes:
 Read a thread:
 
 ```bash
-slk thread get --channel C123 --ts 1710000000.000100 --include users,reactions,files,permalinks --json
+agent-slack thread get --channel C123 --ts 1710000000.000100 --include users,reactions,files,permalinks --json
 ```
 
 Prepare channel-summary input:
 
 ```bash
-slk conversation context C123 --since 24h --include users,reactions,files,threads --format ndjson
+agent-slack conversation context C123 --since 24h --include users,reactions,files,threads --format ndjson
 ```
 
 Search before reading:
 
 ```bash
-slk search context --query "latest on project atlas" --content-types messages,files --json
+agent-slack search context --query "latest on project atlas" --content-types messages,files --json
 ```
 
 Call a new Slack method before the CLI has a wrapper:
 
 ```bash
-slk api call some.newMethod --payload @request.json --json
+agent-slack api call some.newMethod --payload @request.json --json
 ```
 
 ## Build Order

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @eliya-oss/agent-slack
 
+## 0.1.1
+
+### Patch Changes
+
+- Expose `agent-slack` as the primary binary, add the `aslk` alias, and render human-friendly TTY output while preserving JSON for agent and piped runs.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,8 @@
 
 # Agent Slack
 
-Slack context for AI agents, exposed through the `slk` CLI.
+Slack context for AI agents, exposed through the `agent-slack` CLI.
+Short alias: `aslk`.
 
 ```bash
 npm install -g @eliya-oss/agent-slack
@@ -15,11 +16,11 @@ npm install -g @eliya-oss/agent-slack
 ## Usage
 
 ```bash
-slk auth login --oauth --client-id "$SLACK_CLIENT_ID" --client-secret "$SLACK_CLIENT_SECRET" --json
-slk conversation history C123 --limit 50 --json
-slk thread get --channel C123 --ts 1710000000.000100 --include users,permalinks --json
-slk conversation context C123 --include users,threads,permalinks --format ndjson
-slk api call conversations.info --payload '{"channel":"C123"}' --json
+agent-slack auth login --oauth --client-id "$SLACK_CLIENT_ID" --client-secret "$SLACK_CLIENT_SECRET" --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
 ```
 
 ## Skill

package/assets/terminal.svg

@@ -13,20 +13,20 @@
   <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">slk auth status --json</text>
-  <text x="78" y="196" fill="#93C5FD" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{ "ok": true, "profile": "work", "data": { "teamId": "T123" } }</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">slk conversation context C123 --include users,threads --format ndjson</text>
-  <text x="78" y="284" fill="#FDE68A" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{"type":"slack.message","channel_id":"C123","ts":"1710000000.000100","text":"Ship status?"}</text>
-  <text x="78" y="314" fill="#FDE68A" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{"type":"slack.message","channel_id":"C123","thread_ts":"1710000000.000100","text":"Green."}</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">slk thread get --channel C123 --ts 1710000000.000100 --include users --json</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">slk api call conversations.info --payload '{"channel":"C123"}' --json</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">stdout is parseable JSON</text>
+  <text x="70" y="508" fill="#67E8F9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">--json stays parseable</text>
 </svg>

package/dist/adapters/keychain/KeychainTokenStore.js

@@ -13,7 +13,7 @@ export class KeychainTokenStore {
         this.secrets = secrets;
     }
     static fromEnv(env = process.env) {
-        const configDir = env.SLK_CONFIG_DIR ?? join(env.HOME ?? process.cwd(), ".config", "slk");
+        const configDir = env.AGENT_SLACK_CONFIG_DIR ?? env.SLK_CONFIG_DIR ?? join(env.HOME ?? process.cwd(), ".config", "agent-slack");
         return new KeychainTokenStore(join(configDir, "profiles.keychain.json"));
     }
     async getProfile(name) {

package/dist/adapters/live.js

@@ -4,10 +4,14 @@ import { KeychainTokenStore } from "./keychain/KeychainTokenStore.js";
 import { NodeLocalhostOAuthFlow } from "./localhost-oauth/NodeLocalhostOAuthFlow.js";
 import { FileTokenStore } from "./profile-file/FileTokenStore.js";
 import { SlackSdkWebApi } from "./slack-sdk/SlackSdkWebApi.js";
-export const createLiveServices = (env = process.env) => ({
-    tokenStore: env.SLK_TOKEN_STORE === "keychain" ? KeychainTokenStore.fromEnv(env) : FileTokenStore.fromEnv(env),
-    oauthFlow: NodeLocalhostOAuthFlow.fromEnv(env),
-    fileDownloader: new HttpFileDownloader(),
-    slackWebApi: new SlackSdkWebApi(env.SLK_SLACK_API_BASE_URL === undefined ? {} : { slackApiUrl: env.SLK_SLACK_API_BASE_URL }),
-    methodCatalog: new BundledMethodCatalog()
-});
+export const createLiveServices = (env = process.env) => {
+    const tokenStore = env.AGENT_SLACK_TOKEN_STORE ?? env.SLK_TOKEN_STORE;
+    const slackApiUrl = env.AGENT_SLACK_API_BASE_URL ?? env.SLK_SLACK_API_BASE_URL;
+    return {
+        tokenStore: tokenStore === "keychain" ? KeychainTokenStore.fromEnv(env) : FileTokenStore.fromEnv(env),
+        oauthFlow: NodeLocalhostOAuthFlow.fromEnv(env),
+        fileDownloader: new HttpFileDownloader(),
+        slackWebApi: new SlackSdkWebApi(slackApiUrl === undefined ? {} : { slackApiUrl }),
+        methodCatalog: new BundledMethodCatalog()
+    };
+};

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

@@ -9,14 +9,17 @@ export class NodeLocalhostOAuthFlow {
         this.options = options;
     }
     static fromEnv(env = process.env) {
-        const apiBaseUrl = env.SLK_SLACK_API_BASE_URL;
+        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 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.SLK_SLACK_OAUTH_AUTHORIZE_URL ?? (emulatorBaseUrl === undefined ? "https://slack.com/oauth/v2/authorize" : `${emulatorBaseUrl}/oauth/v2/authorize`),
-            tokenUrl: env.SLK_SLACK_OAUTH_ACCESS_URL ?? (apiBaseUrl === undefined ? "https://slack.com/api/oauth.v2.access" : `${apiBaseUrl.replace(/\/?$/, "/")}oauth.v2.access`),
-            ...(env.SLK_OAUTH_REDIRECT_HOST === undefined ? {} : { defaultRedirectHost: env.SLK_OAUTH_REDIRECT_HOST }),
-            ...(env.SLK_OAUTH_REDIRECT_PATH === undefined ? {} : { defaultRedirectPath: env.SLK_OAUTH_REDIRECT_PATH }),
-            ...(env.SLK_OAUTH_TIMEOUT_MS === undefined ? {} : { defaultTimeoutMs: Number(env.SLK_OAUTH_TIMEOUT_MS) })
+            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 }),
+            ...(redirectPath === undefined ? {} : { defaultRedirectPath: redirectPath }),
+            ...(timeoutMs === undefined ? {} : { defaultTimeoutMs: Number(timeoutMs) })
         });
     }
     async login(input) {

package/dist/adapters/profile-file/FileTokenStore.js

@@ -9,15 +9,15 @@ export class FileTokenStore {
         this.envProfile = envProfile;
     }
     static fromEnv(env = process.env) {
-        const configDir = env.SLK_CONFIG_DIR ?? join(env.HOME ?? process.cwd(), ".config", "slk");
-        const token = env.SLK_TOKEN ?? env.SLACK_BOT_TOKEN ?? null;
+        const configDir = env.AGENT_SLACK_CONFIG_DIR ?? env.SLK_CONFIG_DIR ?? join(env.HOME ?? process.cwd(), ".config", "agent-slack");
+        const token = env.AGENT_SLACK_TOKEN ?? env.SLK_TOKEN ?? env.SLACK_BOT_TOKEN ?? null;
         const envProfile = token === null
             ? null
             : {
                 name: ProfileName.default,
                 tokenType: "bot",
                 botToken: token,
-                scopes: (env.SLK_SCOPES ?? "").split(",").filter(Boolean).map(Scope.make)
+                scopes: (env.AGENT_SLACK_SCOPES ?? env.SLK_SCOPES ?? "").split(",").filter(Boolean).map(Scope.make)
             };
         return new FileTokenStore(join(configDir, "profiles.json"), envProfile);
     }

package/dist/application/commands.js

@@ -1,8 +1,9 @@
 import { flagBoolean, flagString, requireFlag, splitCsv } from "../cli/args.js";
-import { describeAllCommands, describeCommandGroup, findCommandMetadata, renderCompletion, renderHumanHelp } from "../cli/metadata.js";
+import { PRIMARY_COMMAND_NAME, describeAllCommands, describeCommandGroup, findCommandMetadata, renderCompletion, renderHumanHelp } from "../cli/metadata.js";
 import { NotAuthenticated, 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";
 import { projectFields } from "../output/projection.js";
 import { getProfile, parseTokenType, requireYes, tokenFor } from "./auth.js";
 import { parseJsonPayload, requirePositional } from "./payload.js";
@@ -147,7 +148,7 @@ export const dispatch = async (parsed, services) => {
 };
 const describePath = (path, error) => {
     const metadata = findCommandMetadata(path);
-    const value = metadata ?? describeCommandGroup(path[0] ?? "slk");
+    const value = metadata ?? describeCommandGroup(path[0] ?? PRIMARY_COMMAND_NAME);
     if (error !== null && metadata === null) {
         throw error;
     }
@@ -184,7 +185,7 @@ const authCommand = async (parsed, services) => {
         return methodCall(parsed, services, { method: "auth.test", payload: {} });
     }
     if (second === "login") {
-        const token = flagString(parsed, "token") ?? process.env.SLK_TOKEN ?? process.env.SLACK_BOT_TOKEN;
+        const token = flagString(parsed, "token") ?? process.env.AGENT_SLACK_TOKEN ?? process.env.SLK_TOKEN ?? process.env.SLACK_BOT_TOKEN;
         if (token !== undefined && !flagBoolean(parsed, "oauth")) {
             const profile = {
                 name: ProfileName.make(profileName),
@@ -195,10 +196,10 @@ 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.SLK_CLIENT_ID;
-        const clientSecret = flagString(parsed, "client-secret") ?? process.env.SLK_CLIENT_SECRET;
+        const clientId = flagString(parsed, "client-id") ?? process.env.AGENT_SLACK_CLIENT_ID ?? process.env.SLK_CLIENT_ID ?? process.env.SLACK_CLIENT_ID;
+        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 SLK_CLIENT_ID/SLK_CLIENT_SECRET");
+            throw new NotAuthenticated("OAuth login needs --client-id/--client-secret or AGENT_SLACK_CLIENT_ID/AGENT_SLACK_CLIENT_SECRET");
         }
         const scopes = splitCsv(flagString(parsed, "scopes"));
         const profile = await services.oauthFlow.login({
@@ -511,7 +512,7 @@ const methodCall = async (parsed, services, input) => {
         items: result.items
     };
 };
-export const renderDispatchResult = (parsed, result) => {
+export const renderDispatchResult = (parsed, result, options = {}) => {
     if (result.rawStdout !== undefined) {
         return result.rawStdout;
     }
@@ -526,7 +527,16 @@ export const renderDispatchResult = (parsed, result) => {
         ...(result.response === undefined ? {} : { paging: pagingFrom(result.response) }),
         ...(result.warnings === undefined ? {} : { warnings: result.warnings })
     });
-    return `${JSON.stringify(envelope, null, 2)}\n`;
+    if (shouldRenderJson(parsed, options)) {
+        return `${JSON.stringify(envelope, null, 2)}\n`;
+    }
+    return renderHumanEnvelope(envelope, {
+        color: options.stdoutIsTty === true && options.env?.NO_COLOR === undefined && !flagBoolean(parsed, "no-color")
+    });
+};
+const shouldRenderJson = (parsed, options) => {
+    const format = flagString(parsed, "format");
+    return flagBoolean(parsed, "json") || format === "json" || options.stdoutIsTty !== true;
 };
 const numberFlag = (parsed, name) => {
     const value = flagString(parsed, name);

package/dist/application/execute.js

@@ -1,13 +1,13 @@
 import { parseArgs } from "../cli/args.js";
 import { errorEnvelope } from "../output/envelope.js";
 import { dispatch, renderDispatchResult } from "./commands.js";
-export const executeCli = async (argv, services) => {
+export const executeCli = async (argv, services, options = {}) => {
     try {
         const parsed = parseArgs(argv);
         const result = await dispatch(parsed, services);
         return {
             exitCode: 0,
-            stdout: renderDispatchResult(parsed, result),
+            stdout: renderDispatchResult(parsed, result, options),
             stderr: ""
         };
     }

package/dist/cli/args.js

@@ -4,6 +4,7 @@ const booleanFlags = new Set([
     "allow-write",
     "help",
     "json",
+    "no-color",
     "raw",
     "trace",
     "yes",

package/dist/cli/metadata.js

@@ -1,3 +1,6 @@
+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 commandMetadata = [
     {
         path: ["describe"],
@@ -5,7 +8,7 @@ export const commandMetadata = [
         flags: ["--json"],
         safety: "read",
         output: "command metadata",
-        examples: ["slk describe --json"]
+        examples: ["agent-slack describe --json"]
     },
     {
         path: ["completion"],
@@ -13,7 +16,7 @@ export const commandMetadata = [
         args: ["bash|zsh"],
         safety: "read",
         output: "shell completion script",
-        examples: ["slk completion zsh > ~/.zfunc/_slk"]
+        examples: ["agent-slack completion zsh > ~/.zfunc/_agent-slack"]
     },
     {
         path: ["auth", "status"],
@@ -21,7 +24,7 @@ export const commandMetadata = [
         flags: ["--profile", "--json"],
         safety: "read",
         output: "profile status",
-        examples: ["slk auth status --json"]
+        examples: ["agent-slack auth status --json"]
     },
     {
         path: ["auth", "login"],
@@ -30,8 +33,8 @@ export const commandMetadata = [
         safety: "read",
         output: "profile status",
         examples: [
-            "slk auth login --oauth --client-id 123.456 --client-secret secret --scopes channels:read,channels:history --json",
-            "SLK_TOKEN=xoxb-... slk 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"
         ]
     },
     {
@@ -40,7 +43,7 @@ export const commandMetadata = [
         flags: ["--profile", "--json"],
         safety: "read",
         output: "scope list",
-        examples: ["slk auth scopes --json"]
+        examples: ["agent-slack auth scopes --json"]
     },
     {
         path: ["auth", "profiles", "list"],
@@ -48,7 +51,7 @@ export const commandMetadata = [
         flags: ["--json"],
         safety: "read",
         output: "profile list",
-        examples: ["slk auth profiles list --json"]
+        examples: ["agent-slack auth profiles list --json"]
     },
     {
         path: ["auth", "logout"],
@@ -56,7 +59,7 @@ export const commandMetadata = [
         flags: ["--profile", "--json"],
         safety: "destructive",
         output: "deleted profile status",
-        examples: ["slk auth logout --profile work --yes --json"]
+        examples: ["agent-slack auth logout --profile work --yes --json"]
     },
     {
         path: ["auth", "test"],
@@ -65,7 +68,7 @@ export const commandMetadata = [
         scopes: [],
         safety: "read",
         output: "Slack auth.test response",
-        examples: ["slk auth test --json"]
+        examples: ["agent-slack auth test --json"]
     },
     {
         path: ["team", "get"],
@@ -74,7 +77,7 @@ export const commandMetadata = [
         scopes: ["team:read"],
         safety: "read",
         output: "team info",
-        examples: ["slk team get --json"]
+        examples: ["agent-slack team get --json"]
     },
     {
         path: ["team", "profile", "get"],
@@ -83,7 +86,7 @@ export const commandMetadata = [
         scopes: ["users.profile:read"],
         safety: "read",
         output: "team profile fields",
-        examples: ["slk team profile get --json"]
+        examples: ["agent-slack team profile get --json"]
     },
     {
         path: ["enterprise", "get"],
@@ -92,7 +95,7 @@ export const commandMetadata = [
         scopes: ["team:read"],
         safety: "read",
         output: "team or enterprise info",
-        examples: ["slk enterprise get --json"]
+        examples: ["agent-slack enterprise get --json"]
     },
     {
         path: ["user", "list"],
@@ -102,7 +105,7 @@ export const commandMetadata = [
         scopes: ["users:read"],
         safety: "read",
         output: "user list",
-        examples: ["slk user list --limit 50 --json"]
+        examples: ["agent-slack user list --limit 50 --json"]
     },
     {
         path: ["user", "get"],
@@ -112,7 +115,7 @@ export const commandMetadata = [
         scopes: ["users:read"],
         safety: "read",
         output: "user info",
-        examples: ["slk user get U123 --json"]
+        examples: ["agent-slack user get U123 --json"]
     },
     {
         path: ["user", "lookup"],
@@ -122,7 +125,7 @@ export const commandMetadata = [
         scopes: ["users:read.email"],
         safety: "read",
         output: "user info",
-        examples: ["slk user lookup --email dev@example.com --json"]
+        examples: ["agent-slack user lookup --email dev@example.com --json"]
     },
     {
         path: ["user", "presence", "get"],
@@ -132,7 +135,7 @@ export const commandMetadata = [
         scopes: ["users:read"],
         safety: "read",
         output: "presence",
-        examples: ["slk user presence get U123 --json"]
+        examples: ["agent-slack user presence get U123 --json"]
     },
     {
         path: ["usergroups", "list"],
@@ -141,7 +144,7 @@ export const commandMetadata = [
         scopes: ["usergroups:read"],
         safety: "read",
         output: "user group list",
-        examples: ["slk usergroups list --json"]
+        examples: ["agent-slack usergroups list --json"]
     },
     {
         path: ["usergroups", "users", "list"],
@@ -151,7 +154,7 @@ export const commandMetadata = [
         scopes: ["usergroups:read"],
         safety: "read",
         output: "user IDs",
-        examples: ["slk usergroups users list S123 --json"]
+        examples: ["agent-slack usergroups users list S123 --json"]
     },
     {
         path: ["api", "call"],
@@ -161,8 +164,8 @@ export const commandMetadata = [
         safety: "unknown",
         output: "Slack Web API response",
         examples: [
-            "slk api call conversations.history --payload '{\"channel\":\"C123\"}' --json",
-            "cat payload.json | slk api call conversations.history -"
+            "agent-slack api call conversations.history --payload '{\"channel\":\"C123\"}' --json",
+            "cat payload.json | agent-slack api call conversations.history -"
         ]
     },
     {
@@ -171,7 +174,7 @@ export const commandMetadata = [
         flags: ["--family", "--json"],
         safety: "read",
         output: "method metadata list",
-        examples: ["slk api methods list --family conversations --json"]
+        examples: ["agent-slack api methods list --family conversations --json"]
     },
     {
         path: ["api", "method", "describe"],
@@ -180,7 +183,7 @@ export const commandMetadata = [
         flags: ["--json"],
         safety: "read",
         output: "method metadata",
-        examples: ["slk api method describe conversations.replies --json"]
+        examples: ["agent-slack api method describe conversations.replies --json"]
     },
     {
         path: ["conversation", "list"],
@@ -189,7 +192,7 @@ export const commandMetadata = [
         scopes: ["channels:read", "groups:read", "im:read", "mpim:read"],
         safety: "read",
         output: "conversation list",
-        examples: ["slk conversation list --types public_channel,private_channel --json"]
+        examples: ["agent-slack conversation list --types public_channel,private_channel --json"]
     },
     {
         path: ["conversation", "history"],
@@ -199,7 +202,7 @@ export const commandMetadata = [
         scopes: ["channels:history", "groups:history", "im:history", "mpim:history"],
         safety: "read",
         output: "message list",
-        examples: ["slk conversation history C123 --limit 20 --json"]
+        examples: ["agent-slack conversation history C123 --limit 20 --json"]
     },
     {
         path: ["conversation", "context"],
@@ -209,7 +212,7 @@ export const commandMetadata = [
         scopes: ["channels:history", "users:read"],
         safety: "read",
         output: "hydrated conversation context",
-        examples: ["slk conversation context C123 --since 24h --include users,threads --format ndjson"]
+        examples: ["agent-slack conversation context C123 --since 24h --include users,threads --format ndjson"]
     },
     {
         path: ["thread", "get"],
@@ -219,7 +222,7 @@ export const commandMetadata = [
         scopes: ["channels:history", "groups:history", "im:history", "mpim:history"],
         safety: "read",
         output: "thread messages",
-        examples: ["slk thread get --channel C123 --ts 1710000000.000100 --include users --json"]
+        examples: ["agent-slack thread get --channel C123 --ts 1710000000.000100 --include users --json"]
     },
     {
         path: ["message", "get"],
@@ -229,7 +232,7 @@ export const commandMetadata = [
         scopes: ["channels:history"],
         safety: "read",
         output: "message",
-        examples: ["slk message get --channel C123 --ts 1710000000.000100 --json"]
+        examples: ["agent-slack message get --channel C123 --ts 1710000000.000100 --json"]
     },
     {
         path: ["message", "permalink"],
@@ -238,7 +241,7 @@ export const commandMetadata = [
         methods: ["chat.getPermalink"],
         safety: "read",
         output: "permalink",
-        examples: ["slk message permalink --channel C123 --ts 1710000000.000100 --json"]
+        examples: ["agent-slack message permalink --channel C123 --ts 1710000000.000100 --json"]
     },
     {
         path: ["search", "context"],
@@ -248,7 +251,7 @@ export const commandMetadata = [
         scopes: ["search:read.public", "search:read.private"],
         safety: "read",
         output: "search context",
-        examples: ["slk search context --query 'project atlas' --json"]
+        examples: ["agent-slack search context --query 'project atlas' --json"]
     },
     {
         path: ["file", "list"],
@@ -257,7 +260,7 @@ export const commandMetadata = [
         scopes: ["files:read"],
         safety: "read",
         output: "file list",
-        examples: ["slk file list --channel C123 --json"]
+        examples: ["agent-slack file list --channel C123 --json"]
     },
     {
         path: ["file", "download"],
@@ -268,11 +271,12 @@ export const commandMetadata = [
         scopes: ["files:read"],
         safety: "read",
         output: "download status",
-        examples: ["slk file download F123 --out ./artifact.pdf --json"]
+        examples: ["agent-slack file download F123 --out ./artifact.pdf --json"]
     }
 ];
 export const describeAllCommands = () => ({
-    name: "slk",
+    name: PRIMARY_COMMAND_NAME,
+    aliases: [SHORT_COMMAND_NAME],
     version: "0.1.0",
     commands: commandMetadata
 });
@@ -285,7 +289,7 @@ export const renderHumanHelp = (path) => {
     const command = findCommandMetadata(path);
     if (command !== null) {
         return [
-            `slk ${command.path.join(" ")}`,
+            `${PRIMARY_COMMAND_NAME} ${command.path.join(" ")}`,
             "",
             command.summary,
             "",
@@ -301,7 +305,7 @@ export const renderHumanHelp = (path) => {
     }
     const commands = path.length === 0 ? commandMetadata : commandMetadata.filter((item) => item.path[0] === path[0]);
     return [
-        "slk",
+        PRIMARY_COMMAND_NAME,
         "",
         "Agent-readable Slack CLI.",
         "",
@@ -313,15 +317,15 @@ export const renderCompletion = (shell) => {
     const words = [...new Set(commandMetadata.flatMap((command) => command.path))];
     const commandWords = commandMetadata.map((command) => command.path.join(" "));
     if (shell === "bash") {
-        return `complete -W '${words.join(" ")}' slk\n`;
+        return `complete -W '${words.join(" ")}' ${COMMAND_NAMES.join(" ")}\n`;
     }
     if (shell === "zsh") {
         return [
-            "#compdef slk",
-            "_slk_commands=(",
+            `#compdef ${COMMAND_NAMES.join(" ")}`,
+            "_agent_slack_commands=(",
             ...commandWords.map((command) => `  '${command}:${summaryFor(command)}'`),
             ")",
-            "_describe 'slk command' _slk_commands",
+            `_describe '${PRIMARY_COMMAND_NAME} command' _agent_slack_commands`,
             ""
         ].join("\n");
     }

package/dist/main.js

@@ -4,7 +4,10 @@ import { Effect } from "effect";
 import { createLiveServices } from "./adapters/live.js";
 import { executeCli } from "./application/execute.js";
 const program = Effect.promise(async () => {
-    const result = await executeCli(process.argv.slice(2), createLiveServices());
+    const result = await executeCli(process.argv.slice(2), createLiveServices(), {
+        stdoutIsTty: process.stdout.isTTY === true,
+        env: process.env
+    });
     if (result.stdout.length > 0) {
         process.stdout.write(result.stdout);
     }

package/dist/output/envelope.js

@@ -44,7 +44,7 @@ export const errorEnvelope = (error) => {
 const suggestionFor = (tag) => {
     switch (tag) {
         case "NotAuthenticated":
-            return "Run slk auth login or provide a seeded profile for tests.";
+            return "Run agent-slack auth login or provide a seeded profile for tests.";
         case "MissingScope":
             return "Reinstall or reauthorize the Slack app with the missing scope.";
         case "SlackRateLimited":

package/dist/output/human.js

@@ -0,0 +1,289 @@
+const codes = {
+    bold: [1, 22],
+    cyan: [36, 39],
+    dim: [2, 22],
+    green: [32, 39],
+    yellow: [33, 39]
+};
+export const renderHumanEnvelope = (envelope, options) => {
+    const paint = (name, value) => options.color ? `\u001b[${codes[name][0]}m${value}\u001b[${codes[name][1]}m` : value;
+    if (isCommandCatalog(envelope.data)) {
+        return `${renderCommandCatalog(envelope.data, paint).join("\n")}\n`;
+    }
+    const metadata = renderMetadata(envelope, paint);
+    const warnings = envelope.warnings.map((warning) => `${paint("yellow", "Warning")}: ${warning}`);
+    const data = renderHumanData(envelope.data, paint);
+    const lines = [
+        `${paint("green", "OK")} ${paint("bold", envelope.method)}`,
+        ...(metadata === "" ? [] : [metadata]),
+        ...(warnings.length === 0 ? [] : warnings),
+        ...(data.length === 0 ? [] : ["", ...data])
+    ];
+    return `${lines.join("\n")}\n`;
+};
+const isCommandCatalog = (value) => {
+    if (!isRecord(value) || typeof value.name !== "string" || !Array.isArray(value.commands)) {
+        return false;
+    }
+    return value.commands.every((command) => isRecord(command) &&
+        Array.isArray(command.path) &&
+        command.path.every((part) => typeof part === "string") &&
+        typeof command.summary === "string");
+};
+const renderCommandCatalog = (catalog, paint) => {
+    const title = catalog.version === undefined ? `${titleCase(catalog.name)} Commands` : "Agent Slack";
+    const aliases = catalog.aliases?.join(", ");
+    const groups = groupCommands(catalog.commands);
+    return [
+        `${paint("bold", title)}${catalog.version === undefined ? "" : ` ${paint("dim", catalog.version)}`}`,
+        paint("dim", "Slack context CLI for agents"),
+        "",
+        `${paint("dim", "Use")}     ${paint("cyan", `${catalog.name} <command> [--json]`)}`,
+        ...(aliases === undefined ? [] : [`${paint("dim", "Alias")}   ${aliases}`]),
+        `${paint("dim", "Output")}  human in terminals, JSON when piped or with --json`,
+        "",
+        ...groups.flatMap((group) => renderCommandGroup(group, paint)),
+        "",
+        paint("dim", `Run ${catalog.name} <command> --help for details.`)
+    ];
+};
+const renderCommandGroup = (group, paint) => {
+    const width = Math.min(34, Math.max(...group.commands.map((command) => commandSignature(command).length)));
+    return [
+        paint("yellow", group.title),
+        ...group.commands.map((command) => {
+            const signature = pad(commandSignature(command), width);
+            const safety = command.safety === "destructive"
+                ? ` ${paint("yellow", "[destructive]")}`
+                : command.safety === "unknown"
+                    ? ` ${paint("yellow", "[review]")}`
+                    : "";
+            return `  ${paint("cyan", signature)}  ${command.summary}${safety}`;
+        }),
+        ""
+    ];
+};
+const groupCommands = (commands) => {
+    const groups = new Map();
+    for (const command of commands) {
+        const key = groupKey(command);
+        groups.set(key, [...(groups.get(key) ?? []), command]);
+    }
+    return commandGroupOrder
+        .map((group) => ({
+        ...group,
+        commands: groups.get(group.key) ?? []
+    }))
+        .filter((group) => group.commands.length > 0);
+};
+const commandGroupOrder = [
+    { key: "system", title: "System" },
+    { key: "auth", title: "Auth" },
+    { key: "workspace", title: "Workspace" },
+    { key: "people", title: "People" },
+    { key: "conversations", title: "Conversations" },
+    { key: "search", title: "Search" },
+    { key: "files", title: "Files" },
+    { key: "surfaces", title: "Slack Objects" },
+    { key: "api", title: "Web API" }
+];
+const groupKey = (command) => {
+    const root = command.path[0];
+    if (root === "describe" || root === "completion") {
+        return "system";
+    }
+    if (root === "team" || root === "enterprise") {
+        return "workspace";
+    }
+    if (root === "user" || root === "usergroups") {
+        return "people";
+    }
+    if (root === "conversation" || root === "thread" || root === "message") {
+        return "conversations";
+    }
+    if (root === "file") {
+        return "files";
+    }
+    if (root === "reaction" || root === "pin" || root === "bookmark" || root === "emoji" || root === "dnd") {
+        return "surfaces";
+    }
+    return root ?? "system";
+};
+const commandSignature = (command) => {
+    const args = command.args?.filter((arg) => arg !== "PAYLOAD_STDIN_MARKER").join(" ");
+    return [command.path.join(" "), args].filter((part) => part !== undefined && part !== "").join(" ");
+};
+const renderMetadata = (envelope, paint) => {
+    const parts = [
+        envelope.profile === null ? undefined : `profile ${envelope.profile}`,
+        envelope.team_id === null ? undefined : `team ${envelope.team_id}`,
+        envelope.enterprise_id === null ? undefined : `enterprise ${envelope.enterprise_id}`,
+        envelope.paging.has_more ? `next ${envelope.paging.next_cursor ?? "cursor"}` : undefined
+    ].filter((part) => part !== undefined);
+    return parts.length === 0 ? "" : paint("dim", parts.join(" | "));
+};
+const renderHumanData = (value, paint) => {
+    if (Array.isArray(value)) {
+        return renderArray(value, paint);
+    }
+    if (isRecord(value)) {
+        const primaryArray = findPrimaryArray(value);
+        const excludedKeys = new Set(primaryArray === null ? [] : [primaryArray.key]);
+        const fieldLines = renderFields(value, excludedKeys, paint);
+        const hasComplexValues = hasVisibleComplexValues(value, excludedKeys);
+        if (primaryArray !== null) {
+            return [
+                ...fieldLines,
+                fieldLines.length === 0 ? "" : "",
+                `${paint("cyan", labelFor(primaryArray.key))} (${primaryArray.items.length})`,
+                ...renderArray(primaryArray.items, paint)
+            ].filter((line) => line !== "");
+        }
+        if (fieldLines.length > 0 && !hasComplexValues) {
+            return fieldLines;
+        }
+    }
+    return ["data:", indent(JSON.stringify(value, null, 2))];
+};
+const findPrimaryArray = (record) => {
+    const preferred = ["messages", "members", "channels", "files", "users", "results", "items"];
+    for (const key of preferred) {
+        const value = record[key];
+        if (Array.isArray(value) && !value.every(isScalar)) {
+            return { key, items: value };
+        }
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (Array.isArray(value) && !value.every(isScalar)) {
+            return { key, items: value };
+        }
+    }
+    return null;
+};
+const renderFields = (record, excludedKeys, paint) => {
+    const entries = Object.entries(record)
+        .filter(([key, value]) => !excludedKeys.has(key) && shouldDisplayField(key, value) && isHumanFieldValue(value))
+        .map(([key, value]) => ({ key, label: labelFor(key), value }))
+        .sort((left, right) => fieldOrder(left.key) - fieldOrder(right.key));
+    if (entries.length === 0) {
+        return [];
+    }
+    const labelWidth = Math.max(...entries.map((entry) => entry.label.length));
+    return entries.map((entry) => `${paint("dim", pad(entry.label, labelWidth))}  ${formatHumanValue(entry.value)}`);
+};
+const hasVisibleComplexValues = (record, excludedKeys) => Object.entries(record).some(([key, value]) => !excludedKeys.has(key) && shouldDisplayField(key, value) && !isHumanFieldValue(value));
+const renderArray = (values, paint) => {
+    if (values.length === 0) {
+        return ["(empty)"];
+    }
+    if (!values.every(isRecord)) {
+        return [indent(JSON.stringify(values, null, 2))];
+    }
+    const rows = values.map((value) => value);
+    const columns = columnsFor(rows);
+    if (columns.length === 0) {
+        return [indent(JSON.stringify(values, null, 2))];
+    }
+    const renderedRows = rows.slice(0, 20).map((row) => columns.map((column) => truncate(formatScalar(row[column]), widthFor(column))));
+    const widths = columns.map((column, index) => Math.max(column.length, ...renderedRows.map((row) => row[index]?.length ?? 0)));
+    const header = columns.map((column, index) => pad(truncate(column, widthFor(column)), widths[index] ?? column.length)).join("  ");
+    const divider = widths.map((width) => "-".repeat(width)).join("  ");
+    const body = renderedRows.map((row) => row.map((cell, index) => pad(cell, widths[index] ?? cell.length)).join("  "));
+    const hiddenCount = values.length - renderedRows.length;
+    return [
+        paint("dim", header),
+        paint("dim", divider),
+        ...body,
+        hiddenCount > 0 ? paint("dim", `... ${hiddenCount} more`) : ""
+    ].filter((line) => line !== "");
+};
+const columnsFor = (rows) => {
+    const preferred = ["id", "channel", "ts", "user", "name", "real_name", "type", "subtype", "text"];
+    const discovered = new Set(rows.flatMap((row) => Object.keys(row).filter((key) => isScalar(row[key]))));
+    const ordered = preferred.filter((key) => discovered.has(key));
+    for (const key of discovered) {
+        if (!ordered.includes(key)) {
+            ordered.push(key);
+        }
+        if (ordered.length >= 5) {
+            break;
+        }
+    }
+    return ordered.slice(0, 5);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isScalar = (value) => value === null || ["boolean", "number", "string"].includes(typeof value);
+const isHumanFieldValue = (value) => isScalar(value) || (Array.isArray(value) && value.every(isScalar));
+const shouldDisplayField = (key, value) => {
+    if (key === "ok" && value === true) {
+        return false;
+    }
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (/^has[A-Z].*Token$/.test(key) && value === false) {
+        return false;
+    }
+    return true;
+};
+const labelOverrides = {
+    botId: "Bot",
+    botToken: "Bot token",
+    channelId: "Channel",
+    enterpriseId: "Enterprise",
+    hasAdminToken: "Admin token",
+    hasAppToken: "App token",
+    hasBotToken: "Bot token",
+    hasUserToken: "User token",
+    messageTs: "Message TS",
+    name: "Name",
+    profile: "Profile",
+    scopes: "Scopes",
+    teamId: "Team",
+    tokenType: "Token",
+    userId: "User"
+};
+const orderedFields = [
+    "name",
+    "teamId",
+    "enterpriseId",
+    "userId",
+    "botId",
+    "tokenType",
+    "hasBotToken",
+    "hasUserToken",
+    "hasAdminToken",
+    "hasAppToken",
+    "scopes"
+];
+const fieldOrder = (key) => {
+    const index = orderedFields.indexOf(key);
+    return index === -1 ? orderedFields.length : index;
+};
+const labelFor = (key) => labelOverrides[key] ?? titleCase(key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/_/g, " "));
+const titleCase = (value) => value.split(" ").map((word) => word.toLowerCase() === "id" ? "ID" : word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+const formatHumanValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.length === 0 ? "(none)" : value.map(formatScalar).join(", ");
+    }
+    if (typeof value === "boolean") {
+        return value ? "yes" : "no";
+    }
+    return formatScalar(value);
+};
+const formatScalar = (value) => {
+    if (value === undefined) {
+        return "";
+    }
+    if (value === null) {
+        return "-";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    return String(value);
+};
+const indent = (value) => value.split("\n").map((line) => `  ${line}`).join("\n");
+const pad = (value, width) => value + " ".repeat(Math.max(0, width - value.length));
+const widthFor = (column) => column === "text" ? 72 : 24;
+const truncate = (value, width) => value.length > width ? `${value.slice(0, Math.max(0, width - 3))}...` : value;

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@eliya-oss/agent-slack",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Slack context CLI for AI agents.",
   "type": "module",
   "packageManager": "pnpm@11.9.0",
   "bin": {
-    "slk": "dist/main.js"
+    "agent-slack": "dist/main.js",
+    "aslk": "dist/main.js"
   },
   "files": [
     "dist",
@@ -24,7 +25,8 @@
     "dev": "tsx src/main.ts",
     "prepack": "pnpm build",
     "release:check": "pnpm check && npm pack --dry-run",
-    "slk": "tsx src/main.ts",
+    "agent-slack": "tsx src/main.ts",
+    "aslk": "tsx src/main.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",

package/skills/agent-slack/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: agent-slack
-description: "Use when Codex needs Slack context through the `slk` CLI: authenticate, inspect profiles/scopes, read channels, messages, threads, files, users, search context, or call Slack Web API methods with agent-readable JSON or NDJSON output."
+description: "Use when Codex needs Slack context through the `agent-slack` CLI: authenticate, inspect profiles/scopes, read channels, messages, threads, files, users, search context, or call Slack Web API methods with agent-readable JSON or NDJSON output."
 ---
 
-# slk CLI
+# agent-slack CLI
 
-Use `slk` as the Slack context boundary. Prefer read-only commands and preserve Slack's permission model: the CLI can only return data allowed by the active token, scopes, channel membership, workspace policy, and Slack plan.
+Use `agent-slack` as the Slack context boundary. `aslk` is the short alias. Prefer read-only commands and preserve Slack's permission model: the CLI can only return data allowed by the active token, scopes, channel membership, workspace policy, and Slack plan.
 
 ## Workflow
 
-1. Check availability: `slk describe --json`.
-2. Check auth: `slk auth status --json`.
+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.
 4. Use specific read commands before raw API calls.
 5. Use `--json` for bounded results and `--format ndjson` for large context streams.
@@ -19,17 +19,17 @@ Use `slk` as the Slack context boundary. Prefer read-only commands and preserve
 ## Common Commands
 
 ```bash
-slk conversation history C123 --limit 50 --json
-slk thread get --channel C123 --ts 1710000000.000100 --include users,permalinks --json
-slk conversation context C123 --include users,threads,permalinks --format ndjson
-slk file download F123 --out ./artifact.bin --json
-slk user get U123 --json
-slk api call conversations.info --payload '{"channel":"C123"}' --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 file download F123 --out ./artifact.bin --json
+agent-slack user get U123 --json
+agent-slack api call conversations.info --payload '{"channel":"C123"}' --json
 ```
 
 ## Safety
 
-- Treat `slk api call` as the escape hatch for missing wrappers.
+- Treat `agent-slack api call` as the escape hatch for missing wrappers.
 - Do not pass write/admin-mutating Slack methods unless the user explicitly asks for mutation and accepts `--allow-write --yes`.
 - Never print token values. `auth status` reports token presence and scopes without secrets.
-- For local repo development, use `pnpm slk -- ...` from the repository root instead of global `slk`.
+- For local repo development, use `pnpm agent-slack -- ...` from the repository root instead of global `agent-slack`.

package/skills/agent-slack/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Slack CLI"
-  short_description: "Use slk to retrieve Slack context"
-  default_prompt: "Use $agent-slack to retrieve Slack channel or thread context with the slk CLI."
+  short_description: "Use agent-slack to retrieve Slack context"
+  default_prompt: "Use $agent-slack to retrieve Slack channel or thread context with the agent-slack CLI."