Instructions for AI coding agents working on this repository.
The Slack CLI is a command-line interface for building apps on the Slack Platform. Written in Go, it provides developers with tools to create, run, deploy, and manage Slack apps locally and remotely.
make build # Build the CLI (includes linting and cleaning)
make build-ci # Build for CI (skips lint and tests)
./bin/slack --version # Run the compiled binarymake test # Run all unit tests
make test testdir=cmd/auth testname=TestLoginCommand # Run specific test
make coverage # View test coverage reportmake lint # Run golangci-lint
go tool golangci-lint version # Verify linter versionAlways run gofmt -w on changed Go files after making edits to ensure proper formatting.
make init # Initialize project (fetch tags, dependencies)
make clean # Remove build artifacts (bin/, dist/)
slack docgen ./docs/reference # Generate command documentationcmd/ Commands (user interface layer)
├── auth/ Authentication commands
├── app/ App management commands
├── platform/ Platform commands (deploy, run, activity)
├── project/ Project commands (create, init, samples)
└── root.go Root command initialization and alias mapping
internal/ Private packages (implementation details)
├── api/ Slack API client and HTTP communication
├── app/ App manifest and client logic
├── auth/ Authentication handling
├── config/ Configuration management
├── hooks/ Hook system for lifecycle events
├── iostreams/ I/O handling (stdin, stdout, stderr)
├── shared/ Shared client factory pattern
└── experiment/ Feature flag system
main.go Entry point with tracing and context setup
Command Aliases: Many commands have shortcut aliases defined in cmd/root.go's AliasMap:
slack login→slack auth loginslack deploy→slack platform deployslack create→slack project create
Client Factory Pattern: internal/shared/clients.go provides a ClientFactory that manages shared clients and configurations across commands:
API()- Slack API clientAuth()- Authentication clientAppClient()- App management clientConfig- Configuration stateIO- I/O streamsFs- File system (afero)
Commands receive the ClientFactory and use it to access functionality.
Context-Based State: The codebase uses context.Context extensively to pass runtime state (session IDs, trace IDs, versions) through the call stack via internal/slackcontext.
Tracing: OpenTracing (Jaeger) is initialized in main.go for observability.
Hook System: internal/hooks/ implements a lifecycle hook system that allows SDK projects to inject custom behavior at key points. The specification exists in docs/reference/hooks files.
Experiment System: Features can be gated behind experiments defined in internal/experiment/experiment.go:
- Add new experiments as constants
- Register in
AllExperimentsslice - Enable permanently via
EnabledExperiments - Use
--experimentflag to toggle
Commands follow this pattern:
- Define in
cmd/<category>/<command>.go - Create a Cobra command with use/short/long descriptions
- Add flags specific to that command
- Implement
RunEfunction that receives clients - Add unit tests in
*_test.goalongside
Example command structure:
func NewExampleCommand(clients *shared.ClientFactory) *cobra.Command {
return &cobra.Command{
Use: "example",
Short: "Brief description",
RunE: func(cmd *cobra.Command, args []string) error {
ctx := cmd.Context()
// Command implementation using clients
return nil
},
}
}- Unit tests live alongside code with
_test.gosuffix - Mock implementations use
_mock.gosuffix - Test code uses syntax compatible with the minimum supported Go version (see
go.mod) - The codebase uses
testifyfor assertions andtestify/mockfor mocking - Mock the
ClientFactoryand its dependencies for testing - Always mock file system operations using
afero.Fsto enable testability
Test function names use the format Test_StructName_FunctionName for methods on a struct, or Test_FunctionName for package-level functions:
func Test_Client_GetAppStatus(t *testing.T) { ... } // struct method
func Test_getKeyLength(t *testing.T) { ... } // package-level functionConstructor functions (NewXYZ) should always be declared first, at the top of the test file. After constructors, test functions should be ordered alphabetically within each file. When a file has logical sections (separated by comments), tests should be alphabetical within each section. Getter and setter functions are grouped together under the base name — ignore the Get or Set prefix when determining order (e.g. Test_AppName and Test_SetAppName both sort under A). Exceptions to alphabetical ordering can be made when it doesn't work well for readability or logical grouping.
Preferred: Map pattern - uses tc for test case variable:
tests := map[string]struct {
input string
expected string
}{...}
for name, tc := range tests {
t.Run(name, func(t *testing.T) {
// use tc.field
})
}- Wrap errors returned across package boundaries with
slackerror.Wrap(err, slackerror.ErrCode)so they carry a structured error code - Register new error codes in
internal/slackerror/errors.go: add a constant and an entry inErrorCodeMap - Error codes are alphabetically ordered in both the constants block and
ErrorCodeMap
Versions use semantic versioning with git tags (format: v*.*.*).
Version is generated dynamically using git describe and injected at build time:
LDFLAGS=-X 'github.com/slackapi/slack-cli/internal/version.Version=`git describe --tags --match 'v*.*.*'`'Versioning Rules:
semver:patch- Bug fixes and changes behind experiment flagssemver:minor- New features (once experiments are removed)semver:major- Breaking changes
When deprecating features, commands, or flags:
- Commands: Add
Deprecatedattribute, optionally setHidden: true - Flags: Print deprecation warning on use, hide with
.Hiddenattribute - Public functionality: Add comment
// DEPRECATED(semver:major): <description and migration path> - Internal functionality: Add comment
// DEPRECATED: <description>
See .github/STYLE_GUIDE.md for conventions on command inputs and outputs.
.golangci.yml- Linter configuration with custom initialisms (CLI, API, SDK, etc.) and staticcheck rules.goreleaser.yml- Release build configuration for multi-platform binariesMakefile- Common development tasks and build scriptsgo.mod- Go module dependencies and minimum Go version (seego.modfor current version).circleci/config.yml- CircleCI workflows for CI/CD pipeline.github/workflows/- GitHub Actions for automated testing and releases.githooks/- Opt-in Git hooks (enable withgit config core.hooksPath .githooks)
When creating commits and PRs, append to the end of the commit message:
Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
Use conventional commit format (feat:, fix:, chore:, etc.) for commit titles.
- Create
cmd/<category>/<command>.go - Implement command using
NewXCommand(clients *shared.ClientFactory) *cobra.Command - Register in
cmd/root.goInit()function - Add tests in
cmd/<category>/<command>_test.go - Run
slack docgen ./docs/referenceto generate docs - Consider adding command alias in
AliasMapif appropriate
Command Long descriptions are parsed as Go text/template by docgen and rendered as MDX for the documentation site. Escape { and [ as \{ and \[ in description text to prevent build errors on the docs site. Available template functions: {{Emoji "name"}}, {{LinkText "url"}}, {{ToBold "text"}}.
- Update
go.modwith the new module version - Run
go mod tidyto updatego.sum - Use
go mod graph | grep <module>to inspect dependency tree
All Slack API interactions go through internal/api/:
client.go- HTTP client setupapp.go- App management API callsauth.go- Authentication API callsdatastore.go- Datastore API calls- Each file has corresponding
*_test.gowith mocks
Always use clients.Fs (afero.Fs) instead of direct os calls to enable testing and mocking.
- The CLI binary in development builds is at
./bin/slack - Official releases use
/usr/local/bin/slack - Set
SLACK_DISABLE_TELEMETRY="true"to disable telemetry during development - View experiments with
slack --help --verbose - Build artifacts are in
bin/(local builds) anddist/(release builds) - The
make buildcommand runs linting automatically before building - When testing locally, always use
./bin/slackto avoid conflicts with globally installed versions