Skip to content

Commit 94e6241

Browse files
joshrotenbergjoshrotenberg
authored
feat: add AGENTS.md and CLI agent skills (#884)
Add AGENTS.md for coding agents working on the redisctl codebase, covering build/test commands, crate architecture, conventions, and project structure. Add 7 CLI skills following the agentskills.io spec: - redisctl-setup: installation and profile configuration - redisctl-cloud-management: Cloud subscription/database lifecycle - redisctl-enterprise-ops: day-to-day Enterprise cluster operations - redisctl-enterprise-admin: RBAC, LDAP, licensing, diagnostics - redisctl-networking: VPC peering, TGW, PSC, PrivateLink - redisctl-database-connect: redis-cli sessions and multi-cluster - redisctl-workflows: end-to-end provisioning and recovery patterns Ref #883
1 parent 400a09f commit 94e6241

8 files changed

Lines changed: 954 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# AGENTS.md
2+
3+
Context and instructions for AI coding agents working on the redisctl project.
4+
5+
## Project Overview
6+
7+
redisctl is a Rust workspace with three crates that share a lockstep version (currently 0.9.1):
8+
9+
| Crate | Path | Purpose |
10+
|-------|------|---------|
11+
| **redisctl-core** | `crates/redisctl-core/` | Shared library: config/profile management, Cloud and Enterprise API clients, error handling |
12+
| **redisctl** | `crates/redisctl/` | CLI binary: commands, workflows, connection management |
13+
| **redisctl-mcp** | `crates/redisctl-mcp/` | MCP server for AI agents: ~371 tools, policy engine, skills system |
14+
15+
## Build and Test
16+
17+
```bash
18+
# Format (required before push)
19+
cargo fmt --all
20+
21+
# Lint (all warnings are errors in CI)
22+
cargo clippy --all-targets --all-features -- -D warnings
23+
24+
# Unit tests
25+
cargo test --workspace
26+
27+
# Integration tests (requires Docker for Redis)
28+
cargo test --workspace --test '*' --all-features
29+
30+
# Reuse Docker containers across test runs
31+
REUSE_CONTAINERS=1 cargo test --workspace --test '*' --all-features
32+
```
33+
34+
**Always run fmt + clippy before pushing.** CI will reject unformatted code or clippy warnings.
35+
36+
## CI Checks
37+
38+
PRs must pass:
39+
1. `cargo fmt --all -- --check`
40+
2. `cargo clippy --all-targets --all-features -- -D warnings`
41+
3. Unit tests per crate (parallel)
42+
4. Integration tests
43+
5. Platform builds (Linux required; macOS and Windows are optional)
44+
45+
## Crate Architecture
46+
47+
### Feature Flags
48+
49+
**redisctl** (CLI):
50+
- `default = ["full", "secure-storage"]`
51+
- `full = ["cloud", "enterprise", "upload"]`
52+
- `secure-storage` enables keyring-based credential storage
53+
54+
**redisctl-mcp** (MCP server):
55+
- `default = ["http", "cloud", "enterprise", "database"]`
56+
- Each toolset (`cloud`, `enterprise`, `database`) can be compiled independently
57+
58+
### Key Patterns
59+
60+
**database_tool! macro** (`crates/redisctl-mcp/src/tools/macros.rs`):
61+
Generates MCP tool structs with safety annotations. Three safety tiers:
62+
- `database_tool!(read_only, ...)` -- no side effects
63+
- `database_tool!(write, ...)` -- creates or modifies data
64+
- `database_tool!(destructive, ...)` -- irreversible operations
65+
66+
Field attributes like `#[serde(...)]` pass through the macro. Numeric parameters that might arrive as strings from MCP clients use custom deserializers from `serde_helpers.rs`.
67+
68+
**mcp_module! macro**: Generates `TOOL_NAMES` constant and `router()` function for each tool sub-module.
69+
70+
**Policy system** (`crates/redisctl-mcp/src/policy.rs`): TOML-based policy engine with three safety tiers (ReadOnly, ReadWrite, Full), per-toolset overrides, and allow/deny lists.
71+
72+
**Profile system** (`crates/redisctl-core/`): TOML config at `~/.config/redisctl/config.toml` with profiles for Cloud, Enterprise, and direct Redis connections. Supports env var substitution.
73+
74+
### Module Organization
75+
76+
MCP tools are organized into toolsets with sub-modules:
77+
```
78+
tools/
79+
redis/ # ~125 tools: server, keys, structures, json, search, diagnostics, bulk
80+
cloud/ # ~147 tools: subscriptions, account, networking, fixed
81+
enterprise/ # ~91 tools: cluster, databases, rbac, observability, proxy, services
82+
profile.rs # 8 tools: profile management
83+
```
84+
85+
CLI commands mirror this structure:
86+
```
87+
cli/
88+
cloud.rs # Cloud subcommands
89+
enterprise.rs # Enterprise subcommands
90+
mod.rs # Top-level command tree
91+
```
92+
93+
## Conventions
94+
95+
### Commits
96+
97+
Follow [Conventional Commits](https://www.conventionalcommits.org/):
98+
- `feat:` new feature (minor version bump)
99+
- `fix:` bug fix (patch bump)
100+
- `docs:` documentation only
101+
- `refactor:` no behavior change
102+
- `test:` test additions or fixes
103+
- `chore:` maintenance
104+
105+
Scope by crate when relevant: `feat(mcp):`, `fix(core):`, `docs(cli):`.
106+
107+
### Code Style
108+
109+
- Rust edition 2024, MSRV 1.90+
110+
- No `unwrap()` in production code -- use proper error handling
111+
- Prefer `anyhow` for CLI errors, `tower_mcp::Error` for MCP tool errors
112+
- Tool descriptions are the primary documentation for MCP tools -- keep them accurate and concise
113+
114+
### PRs
115+
116+
- Use feature branches (`feat/`, `fix/`, `docs/`)
117+
- Open Draft PRs early
118+
- Squash and merge to main
119+
- Versions are bumped automatically by release-plz based on commit types
120+
121+
## Dependencies
122+
123+
API client crates are external git dependencies on the `main` branch:
124+
- `redis-cloud` from `github.com/redis-developer/redis-cloud-rs`
125+
- `redis-enterprise` from `github.com/redis-developer/redis-enterprise-rs`
126+
127+
These are published separately and versioned independently.
128+
129+
## MCP Skills
130+
131+
Skills are workflow templates in `crates/redisctl-mcp/skills/` following the [agentskills.io spec](https://agentskills.io/specification):
132+
133+
```
134+
skills/
135+
index-advisor/SKILL.md # Recommend search index schemas
136+
query-tuning/SKILL.md # Optimize queries with FT.EXPLAIN/FT.PROFILE
137+
index-ab-test/SKILL.md # Compare multiple index configurations
138+
```
139+
140+
Each SKILL.md has YAML frontmatter (`name`, `description`) and a markdown body with step-by-step instructions that reference MCP tools.
141+
142+
## License
143+
144+
MIT OR Apache-2.0

‎skills/redisctl-cloud-management/SKILL.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
name: redisctl-cloud-management
3+
description: Manage Redis Cloud subscriptions, databases, and resources via the redisctl CLI. Use when provisioning, updating, or monitoring Redis Cloud infrastructure.
4+
---
5+
6+
## Overview
7+
8+
Manage the full lifecycle of Redis Cloud resources: subscriptions, databases, users, ACLs, and tasks.
9+
10+
## Subscriptions
11+
12+
```bash
13+
# List all subscriptions
14+
redisctl cloud subscription list
15+
16+
# Get subscription details
17+
redisctl cloud subscription get --id 12345
18+
19+
# Create a subscription (JSON input)
20+
redisctl cloud subscription create --data '{...}'
21+
22+
# Update a subscription
23+
redisctl cloud subscription update --id 12345 --data '{...}'
24+
25+
# Delete a subscription
26+
redisctl cloud subscription delete --id 12345
27+
```
28+
29+
## Databases
30+
31+
```bash
32+
# List databases in a subscription
33+
redisctl cloud database list --subscription-id 12345
34+
35+
# Get database details
36+
redisctl cloud database get --subscription-id 12345 --id 67890
37+
38+
# Create a database
39+
redisctl cloud database create --subscription-id 12345 --data '{...}'
40+
41+
# Update a database
42+
redisctl cloud database update --subscription-id 12345 --id 67890 --data '{...}'
43+
44+
# Delete a database
45+
redisctl cloud database delete --subscription-id 12345 --id 67890
46+
47+
# Pause/recover a database
48+
redisctl cloud database pause --subscription-id 12345 --id 67890
49+
redisctl cloud database recover --subscription-id 12345 --id 67890
50+
51+
# Backup a database
52+
redisctl cloud database backup --subscription-id 12345 --id 67890
53+
```
54+
55+
## Essentials / Fixed Tier
56+
57+
For smaller, fixed-price databases:
58+
59+
```bash
60+
redisctl cloud fixed-subscription list
61+
redisctl cloud fixed-database list --subscription-id 12345
62+
redisctl cloud fixed-database create --subscription-id 12345 --data '{...}'
63+
```
64+
65+
## Task Tracking
66+
67+
Cloud operations are async. Track tasks:
68+
69+
```bash
70+
# List recent tasks
71+
redisctl cloud task list
72+
73+
# Get task status
74+
redisctl cloud task get --id <task-id>
75+
76+
# Wait for a task to complete
77+
redisctl cloud task wait --id <task-id>
78+
```
79+
80+
## Workflows
81+
82+
Multi-step operations:
83+
84+
```bash
85+
# Complete subscription setup with optional database
86+
redisctl cloud workflow subscription-setup
87+
```
88+
89+
## Cost Reports
90+
91+
```bash
92+
# Generate a cost report (FOCUS format)
93+
redisctl cloud cost-report generate --start 2026-01-01 --end 2026-01-31
94+
95+
# Download a generated report
96+
redisctl cloud cost-report download --id <report-id>
97+
98+
# Generate and download in one step
99+
redisctl cloud cost-report export --start 2026-01-01 --end 2026-01-31
100+
```
101+
102+
## Account Management
103+
104+
```bash
105+
# Get account details
106+
redisctl cloud account get
107+
108+
# List/manage users
109+
redisctl cloud user list
110+
redisctl cloud user create --data '{...}'
111+
112+
# ACL management
113+
redisctl cloud acl list
114+
redisctl cloud acl create --data '{...}'
115+
```
116+
117+
## Tips
118+
119+
- Use `--profile <name>` to target a specific Cloud profile
120+
- Use `--output json` for machine-readable output
121+
- Most create/update commands accept `--data` with a JSON payload or `--file` for a JSON file
122+
- Task IDs are returned from async operations -- use `cloud task wait` to block until completion

‎skills/redisctl-database-connect/SKILL.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
name: redisctl-database-connect
3+
description: Connect to Redis databases using the redisctl CLI. Use when opening redis-cli sessions, managing connection profiles, or working with multiple Redis clusters.
4+
---
5+
6+
## Overview
7+
8+
Connect to Redis databases using profile-based credential management. Supports direct Redis connections, Cloud databases, and Enterprise databases.
9+
10+
## Quick Connect
11+
12+
```bash
13+
# Open redis-cli using the default database profile
14+
redisctl db open
15+
16+
# Open redis-cli with a specific profile
17+
redisctl db open --profile my-redis
18+
```
19+
20+
## Profile-Based Connection Management
21+
22+
### Create Database Profiles
23+
24+
```bash
25+
# Local Redis
26+
redisctl profile set local --type database --url "redis://localhost:6379"
27+
28+
# Redis with password
29+
redisctl profile set staging --type database --url "redis://:password@host:6379"
30+
31+
# Redis with TLS
32+
redisctl profile set prod --type database --url "rediss://host:6380"
33+
34+
# Set as default
35+
redisctl profile default-database local
36+
```
37+
38+
### Multi-Cluster Workflows
39+
40+
Create profiles for each environment:
41+
42+
```bash
43+
redisctl profile set dev-redis --type database --url "redis://dev:6379"
44+
redisctl profile set staging-redis --type database --url "rediss://staging:6380"
45+
redisctl profile set prod-redis --type database --url "rediss://prod:6380"
46+
```
47+
48+
Switch between them:
49+
50+
```bash
51+
# Connect to dev
52+
redisctl db open --profile dev-redis
53+
54+
# Connect to staging
55+
redisctl db open --profile staging-redis
56+
```
57+
58+
## Raw API Access
59+
60+
For operations not covered by specific commands:
61+
62+
```bash
63+
# Cloud API
64+
redisctl api cloud GET /subscriptions
65+
redisctl api cloud POST /subscriptions/12345/databases --data '{...}'
66+
67+
# Enterprise API
68+
redisctl api enterprise GET /v1/bdbs
69+
redisctl api enterprise PUT /v1/bdbs/1 --data '{...}'
70+
```
71+
72+
## Tips
73+
74+
- Database profile URLs follow the standard Redis URI scheme: `redis://[user:password@]host[:port][/db]`
75+
- Use `rediss://` (double s) for TLS connections
76+
- Profile credentials support environment variable substitution: `--url "redis://:${REDIS_PASSWORD}@host:6379"`
77+
- Run `redisctl profile validate` to test all profile connections

0 commit comments

Comments
 (0)