slack-rs
A Slack CLI tool written in Rust that provides comprehensive access to the Slack Web API using OAuth authentication.
Overview
slack-rs is a command-line tool designed for interacting with Slack workspaces using your personal OAuth credentials. It supports multiple workspace profiles, secure token storage, and provides both generic API access and convenient wrapper commands for common operations.
This tool is designed following the Agentic CLI Design principles, making it optimized for AI agents and automated workflows with structured output, non-interactive operation, idempotent behavior, and safe-by-default design.
Key Features
- 🔐 OAuth Authentication with PKCE flow
- 🏢 Multiple Workspace Support via profiles
- 🔒 Secure Token Storage using file-based storage
- 🔄 Profile Import/Export with encryption
- 📡 Generic API Access - call any Slack Web API method
- 🛠️ Wrapper Commands for common operations
- 🔁 Smart Retry Logic with exponential backoff and rate limit handling
TL;DR
# Install from crates.io
# Or build from source
Installation
Prerequisites
- Rust 1.70+ (tested with 1.92.0)
- A Slack app with OAuth credentials (create one here)
Install from crates.io (Recommended)
The binary will be installed to ~/.cargo/bin/slack-rs (ensure ~/.cargo/bin is in your PATH).
Build from Source
The binary will be available at target/release/slack-rs.
Install from Local Source
Quick Start
1. Set Up OAuth Credentials
Quick Setup: Using App Manifest (Recommended)
The most recommended login flow is to install cloudflared and use --cloudflared.
In this mode, slack-rs auth login generates a Slack App Manifest for you (and copies it to your clipboard).
The intended flow is:
- Create a Slack app and get credentials:
- Go to https://api.slack.com/apps
- Click "Create New App" ("From scratch" is fine)
- In "Basic Information" → "App Credentials", copy your Client ID and Client Secret
- Install cloudflared:
- Start login with --cloudflared (manifest is generated automatically):
# You'll be prompted for the client secret (hidden) # A manifest YAML is generated, saved, and copied to clipboard - Paste the generated YAML into Slack:
- In your Slack app settings, open "App Manifest"
- Paste the generated YAML (from clipboard or
~/.config/slack-rs/<profile>_manifest.yml) - Apply the changes
- Return to the terminal and press Enter:
- The CLI opens your browser
- Click "Allow"
- The CLI exchanges the code for tokens and saves them securely
💡 Manifest Benefits:
- ✅ Redirect URL and scopes are configured for you
- ✅ Less manual Slack UI configuration
- ✅ Manifest is saved to
~/.config/slack-rs/<profile>_manifest.ymland copied to clipboard (best effort) - ✅ Easy to reproduce and share
Customizing Scopes:
If you need different scopes, change the scopes you pass to auth login (or edit the manifest YAML before pasting it into Slack).
Flags:
--bot-scopes <scopes>: comma-separated list orall--user-scopes <scopes>: comma-separated list orall
Common scopes:
chat:write- Post messagesusers:read- View userschannels:read- List public channelsfiles:read- Access filessearch:read- Search workspace contentreactions:write- Add/remove reactions- See full list: https://api.slack.com/scopes
Manual Setup (Alternative)
If you prefer manual configuration:
- Navigate to Slack API: Go to https://api.slack.com/apps
- Create an app:
- Click "Create New App"
- Choose "From scratch"
- Name your app (e.g., "My Slack CLI")
- Select a development workspace
- Configure OAuth & Permissions:
- In the left sidebar, click "OAuth & Permissions"
- Scroll to "Redirect URLs" section
- Add redirect URL:
http://127.0.0.1:8765/callback - Click "Save URLs"
- Add OAuth Scopes:
- Scroll to "Scopes" section under "User Token Scopes"
- Add required scopes for your use case:
chat:write- Post messagesusers:read- View userschannels:read- List public channelssearch:read- Search workspace content- Add more as needed based on API methods you'll use
- Get your credentials:
- Go to "Basic Information" → "App Credentials"
- Copy your Client ID (looks like
123456789012.1234567890123) - Click "Show" and copy your Client Secret (looks like
abcdef1234567890abcdef1234567890)
Providing Credentials
Option A: Save credentials to profile (recommended for most users):
# Save OAuth config to profile (will be prompted for client secret)
# Then authenticate using saved config
Option B: Provide during login (quick one-time use):
# Provide client ID as argument, secret will be prompted securely
Option C: Interactive prompts:
# Tool will prompt for both client ID and secret
# Enter OAuth client ID: [type your client ID]
# Enter OAuth client secret: [type your secret - hidden]
💡 Pro Tip: Use Option A for persistent configuration.
2. Authenticate
Login to your Slack workspace:
# Method 1: Using saved OAuth config (recommended)
# Method 2: Provide client ID during login
# Method 3: Interactive prompts
What happens during login:
- Credentials collected: Client ID and secret are obtained (from saved profile/file storage, CLI args, or prompts)
When using --cloudflared:
2. Tunnel started: cloudflared tunnel is started and a public redirect URL is determined
3. Manifest generated: A Slack App Manifest YAML is generated, saved, and copied to clipboard (best effort)
4. You paste the manifest in Slack: Configure your Slack app using the generated manifest
5. Press Enter to continue: The CLI starts the OAuth flow
OAuth flow: 6. Browser opens: OAuth authorization page opens automatically 7. User authorization: Click "Allow" to grant permissions to your app 8. Callback handled: Callback server receives OAuth callback with authorization code 9. Token exchange: Code is exchanged for access token 10. Secure storage: Profile and token are saved securely
- Profile metadata →
~/.config/slack-rs/profiles.json - Access token → file storage (file storage/Credential Manager)
After successful authentication:
✓ Authentication successful!
Profile 'my-workspace' saved.
Per-Profile OAuth Settings:
- ✅ Each profile can store its own OAuth client ID, redirect URI, and scopes
- 💾 OAuth config saved in
~/.config/slack-rs/profiles.json - 🔒 Client secret saved securely in file storage (prompted only if missing)
- 🔄 Subsequent logins reuse saved configuration automatically
Using Tunneling Services for Remote Authentication
When authenticating from a remote server or environment where localhost is not accessible (e.g., SSH, Docker, cloud instances), the most recommended flow is:
- Install cloudflared
- Run
slack-rs auth login ... --cloudflared
This avoids manually starting a tunnel or managing redirect URLs.
Method A: Built-in Cloudflare Tunnel Support (Easiest)
slack-rs also supports Cloudflare Tunnel with automatic management:
-
Install cloudflared: Download from Cloudflare
-
Configure Slack App with cloudflared redirect URL:
- Go to https://api.slack.com/apps → Your App → OAuth & Permissions
- Add redirect URL:
https://your-tunnel.trycloudflare.com/callback(you'll get the exact URL from cloudflared) - Click "Save URLs"
-
Authenticate with --cloudflared flag:
# The tool will automatically start cloudflared and handle the tunnel # Or with client ID
With --cloudflared, you do not need to manually start a tunnel or copy/paste a tunnel URL into your config.
The CLI starts the tunnel, generates a manifest containing the correct redirect URL, and copies it to your clipboard.
You only need to paste the manifest into Slack and press Enter to continue.
The --cloudflared flag automatically:
- Starts a Cloudflare Tunnel on port 8765
- Displays the public URL for your redirect URI
- Handles the OAuth callback through the tunnel
- Closes the tunnel after authentication
Method B: Manual Tunnel Setup (Advanced)
If you prefer to manage the tunnel yourself:
-
Start cloudflared manually:
# cloudflared -
Configure Slack App with the tunnel URL:
- Add the tunnel URL as redirect URI (e.g.,
https://xyz-def-ghi.trycloudflare.com/callback)
- Add the tunnel URL as redirect URI (e.g.,
-
Authenticate with custom redirect URI:
If you are using the manifest-based flow described above, the manual config oauth set --redirect-uri ... step is usually unnecessary.
Using --cloudflared avoids having to manually manage the tunnel URL.
Security Notes:
- ⚠️ Tunnel URLs are temporary and change each time you restart the service
- ⚠️ Anyone with the tunnel URL can access your callback endpoint during authentication
- ✅ The built-in tunnel support automatically closes the tunnel after authentication
- ✅ Tunnels are only active during the authentication process
ngrok status
The --ngrok flag exists in the CLI help, but ngrok tunnel automation is not implemented in this version.
3. Make API Calls
Generic API call:
Check authentication status:
View saved OAuth configuration:
List all profiles:
Usage
Authentication Commands
Login
Authenticate with a Slack workspace and save credentials.
# Basic login (uses saved profile or prompts)
# Login with specific client ID
# Login with Cloudflare Tunnel (for remote/SSH environments)
# Examples:
Flags:
--client-id <id>: Specify OAuth client ID--cloudflared: Automatically start Cloudflare Tunnel for remote authentication
Note: --ngrok exists in the CLI help, but ngrok tunnel automation is not implemented in v0.1.6.
Status
Check authentication status and profile information.
# Check specific profile
# Check default profile
# Example output:
# Profile: my-workspace
# Team: My Team (T123456)
# User: John Doe (U789012)
# Client ID: 123456789012.123456789012
# Status: ✓ Authenticated
List
Display all saved profiles.
# Example output:
# Profiles:
# • default (My Team / john.doe)
# • dev-workspace (Dev Team / jane.smith)
# • prod-workspace (Prod Team / jane.smith)
Rename
Rename an existing profile.
# Example:
Logout
Remove profile and delete all associated credentials.
# Example:
# ✓ Profile 'old-workspace' removed
# ✓ Credentials deleted from file storage
Export
Create encrypted backup of profiles.
# Export single profile
# Export all profiles
# Examples:
# With environment variable (for automation)
Flags:
--profile <name>: Export specific profile--all: Export all profiles--out <file>: Output file path--passphrase-prompt: Prompt for passphrase securely (recommended)
Import
Restore profiles from encrypted backup.
# Import single profile
# Import all profiles
# Examples:
# With environment variable
Flags:
--profile <name>: Import specific profile--all: Import all profiles from file--in <file>: Input file path--passphrase-prompt: Prompt for passphrase securely (recommended)
Configuration Commands
OAuth Configuration Management
Manage OAuth settings for each profile independently.
Set OAuth configuration:
# Examples:
# Use comprehensive scope preset
Show OAuth configuration:
# Example output:
# OAuth configuration for profile 'my-workspace':
# Client ID: 123456789012.1234567890123
# Redirect URI: http://127.0.0.1:8765/callback
# Scopes: chat:write, users:read, channels:read
# Client secret: (saved in file storage)
Delete OAuth configuration:
# Example:
# ✓ OAuth configuration deleted for profile 'old-workspace'
Per-Profile OAuth Settings
Each profile can store its own OAuth configuration, enabling flexible multi-workspace and multi-app workflows.
Benefits:
- ✅ Different Slack apps per workspace: Use separate apps for different teams
- ✅ Development/Production separation: Test with dev app, deploy with prod app
- ✅ Granular permission control: Different scopes for different profiles
- ✅ Persistent configuration: Save OAuth settings once, reuse forever
- ✅ Team collaboration: Each team member can use their own Slack app
- ✅ Easy switching: No need to re-enter credentials when switching profiles
How it works:
| Step | Action | Storage Location |
|---|---|---|
| 1️⃣ | Set OAuth config via config oauth set |
~/.config/slack-rs/profiles.json + file storage |
| 2️⃣ | Authenticate via auth login |
Browser OAuth flow |
| 3️⃣ | Access token saved securely | file storage |
| 4️⃣ | On re-login, saved config is reused | Auto-loaded from profile |
Examples:
# Scenario 1: Development workspace with dev app
# Scenario 2: Production workspace with prod app and comprehensive scopes
# Scenario 3: Re-authenticate dev-workspace (reuses saved config)
# ℹ Using saved OAuth configuration
# [Browser opens automatically]
# Scenario 4: Check current OAuth configuration
Security Notes:
- Client IDs: Saved in profile JSON (not sensitive per OAuth 2.0 spec)
- Client Secrets: Saved securely in file storage (file storage/Credential Manager)
- Access Tokens: Always saved securely in file storage
- Configuration Files: Profile metadata stored in
~/.config/slack-rs/profiles.jsonwith 0600 permissions
API Calls
Generic API access:
# Examples:
Form-encoded arguments:
Output Format
All commands output JSON with a unified envelope structure that includes both the Slack API response and execution metadata.
Default output (with envelope):
The meta object provides useful context:
profile_name: Profile used for the request (null if not specified)team_id: Slack team/workspace IDuser_id: User ID from the profilemethod: Slack API method calledcommand: CLI command executed (e.g., "api call", "conv list", "msg post")
Raw output (Slack API response only):
Use the --raw flag to get the Slack API response without the envelope wrapper. This is useful for:
- Compatibility with existing scripts that expect raw Slack responses
- Piping output directly to
jqor other tools - Simpler output when metadata is not needed
# With envelope (default)
# Output includes both "response" and "meta"
# Raw Slack API response only
# Output is the Slack API response without envelope
# Works with all commands
Accessing data with jq:
# With envelope (default) - access response data
|
# With envelope - access metadata
|
# Raw output - direct access (for backward compatibility)
|
Migration guide for existing scripts:
If you have existing scripts that parse the output, you can:
- Add
--rawflag to maintain current behavior - Update scripts to extract from
.responsefield - Optionally use
.metafor additional context
# Old script (worked before, but now needs update)
CHANNEL=
# Option 1: Use --raw flag (quick fix)
CHANNEL=
# Option 2: Extract from .response (recommended)
CHANNEL=
# Option 3: Use metadata too
RESULT=
Configuration
Environment Variables
Only the following environment variables are supported by the current implementation. OAuth client credentials are configured via slack-rs config oauth set (not environment variables).
| Variable | Description | Default | Use Case |
|---|---|---|---|
SLACKCLI_ALLOW_WRITE |
Control write operations (post/update/delete messages). Values: true, 1, yes (allow) or false, 0, no (deny) |
true |
Safety in production environments |
SLACK_OAUTH_BASE_URL |
Custom OAuth base URL for testing or private Slack installations. Example: https://custom-slack.example.com |
https://slack.com |
Testing, enterprise Slack instances |
Setting environment variables:
# Example: Prevent accidental write operations
# Example: Non-interactive export/import passphrase
# Example: Use custom OAuth base URL (testing)
Profile Storage
- Profile metadata:
~/.config/slack-rs/profiles.json(Linux/macOS) or%APPDATA%\slack-rs\profiles.json(Windows) - Sensitive credentials: file storage (~/.config/slack-rs/tokens.json with 0600 permissions)
Each profile stores:
- In JSON file:
team_id,user_id,team_name,user_name,client_id,redirect_uri,scopes - In file storage: Access token and client secret (when saved via
config oauth setor export/import)
Write Operation Protection
Write operations (posting, updating, deleting messages, and managing reactions) are controlled by the SLACKCLI_ALLOW_WRITE environment variable:
- Default behavior (variable not set): Write operations are allowed
- Deny write operations: Set
SLACKCLI_ALLOW_WRITE=falseorSLACKCLI_ALLOW_WRITE=0 - Explicitly allow: Set
SLACKCLI_ALLOW_WRITE=trueorSLACKCLI_ALLOW_WRITE=1
Example: Preventing accidental write operations
# Deny all write operations
# This will fail with an error
# Error: Write operation denied. Set SLACKCLI_ALLOW_WRITE=true to enable write operations
# Re-enable write operations
Security
Credential Storage
Access Tokens: All access tokens are stored securely in your operating system's credential manager:
- Token storage: ~/.config/slack-rs/tokens.json
- Windows: Credential Manager
Tokens are never stored in plain text files or logged to the console.
Client Keys:
- Client IDs: Stored in profile metadata file (
~/.config/slack-rs/profiles.json). These are not considered sensitive as they're part of OAuth public flow. - Client Secrets: Stored securely in file storage when provided (via
config oauth setor duringauth login). If not present in file storage, the CLI prompts for it.
Profile Export/Import
Profile export/import enables secure backup and migration of your authentication profiles between machines or for disaster recovery.
What Gets Exported
When you export a profile, the following data is included in the encrypted file:
- Profile metadata: team ID, user ID, team name, user name, client ID
- Access token: OAuth access token for API calls
- Client secret: (Optional) OAuth client secret if you want to save it for convenience
Export Profiles
Export a single profile:
# With passphrase prompt (recommended)
# With environment variable
Export all profiles:
# Export all profiles at once
# Without confirmation prompt
Import Profiles
Import a single profile:
# Import with new profile name
# Import all profiles from file (will prompt for each)
Using environment variable for automation:
Security Details
- Encryption: AES-256-GCM (industry-standard authenticated encryption)
- Key Derivation: Argon2id with random salt (memory-hard, resistant to GPU attacks)
- File Permissions: Automatically set to
0600(owner read/write only)
Use Cases
- Backup: Create encrypted backups of your profiles before system changes
- Migration: Transfer profiles to a new machine or OS
- Team Sharing: Share access credentials with team members (ensure secure passphrase exchange)
- Disaster Recovery: Restore profiles after system failure or reinstallation
Best Practices
✅ Do:
- Use strong, unique passphrases (16+ characters with mixed case, numbers, symbols)
- Store exported files in secure locations (encrypted drives, password managers)
- Use
--passphrase-promptin scripts to avoid password in shell history - Delete old export files after successful import
❌ Don't:
- Commit export files to version control (add
*.encto.gitignore) - Share export files over unencrypted channels (use secure file transfer)
- Reuse passphrases across different export files
- Store passphrases in plain text files
⚠️ Warning: Exported files contain sensitive credentials including access tokens and potentially client secrets. Treat them like passwords and store securely.
Development
Git Hooks
This project uses prek for managing git hooks. Prek is a Rust-based implementation of pre-commit that requires no Python runtime.
Install prek:
# macOS/Linux
|
# Homebrew
# cargo
Enable hooks:
Run hooks manually:
# Run all hooks on all files
# Run specific hooks
# List available hooks
The hooks will automatically run before each commit and include:
cargo fmt- Format Rust codecargo clippy- Lint with clippy- Trailing whitespace checks
- File endings checks
- YAML/TOML syntax validation
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for development setup, coding guidelines, and submission process.
Roadmap
- Enhanced wrapper commands for common operations
- Support for slash commands
- Interactive mode for profile management
- Improved error messages with suggestions
- Internationalization (i18n) for English and Japanese
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Built with Rust
- Uses reqwest for HTTP
- Secure storage with file-based token storage
- OAuth implementation inspired by oauth2-rs
Support
Note: This is an unofficial tool and is not affiliated with or endorsed by Slack Technologies, Inc.