Skip to content

Commit 903a570

Browse files
joshrotenbergjoshrotenberg
authored
docs: complete remaining documentation improvements (#258)
- Add example config file to README showing TOML format - Enhance Quick Start with verification steps and common first commands - Add Docker usage examples to README with quick commands - Create comprehensive shell completions guide for all supported shells - Add Common Recipes placeholder that previews upcoming workflow system Part of #251
1 parent 94857e8 commit 903a570

File tree

4 files changed

+384
-8
lines changed

4 files changed

+384
-8
lines changed

‎README.md‎

Lines changed: 58 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -61,22 +61,72 @@ Profiles are stored in:
6161
- **Linux/macOS**: `~/.config/redisctl/config.toml`
6262
- **Windows**: `%APPDATA%\redis\redisctl\config.toml`
6363

64-
### 2. Basic Commands
64+
Example configuration file:
65+
```toml
66+
default_profile = "cloud-prod"
67+
68+
[profiles.cloud-prod]
69+
deployment_type = "cloud"
70+
api_key = "${REDIS_CLOUD_API_KEY}"
71+
api_secret = "${REDIS_CLOUD_API_SECRET}"
72+
73+
[profiles.enterprise-dev]
74+
deployment_type = "enterprise"
75+
url = "https://localhost:9443"
76+
username = "admin@redis.local"
77+
password = "${REDIS_ENTERPRISE_PASSWORD}"
78+
insecure = true
79+
```
80+
81+
### 2. Verify Setup & First Commands
6582

6683
```bash
67-
# List databases (auto-detects deployment type from profile)
68-
redisctl database list
84+
# Test your connection
85+
redisctl api cloud get / # For Cloud
86+
redisctl api enterprise get /v1/cluster # For Enterprise
87+
88+
# View your configuration
89+
redisctl profile list # Show all profiles
90+
redisctl profile path # Show config file location
91+
92+
# Common first commands
93+
redisctl database list # List all databases
94+
redisctl cloud subscription list # List Cloud subscriptions
95+
redisctl enterprise node list # List Enterprise nodes
6996

70-
# Get database details with formatted output
71-
redisctl database get 12345 --output table
97+
# Get detailed output
98+
redisctl database get 12345 --output table # Table format
99+
redisctl database list -o json | jq # JSON with jq
72100

73-
# Create a database and wait for completion
101+
# Create resources and wait for completion
74102
redisctl cloud database create --data @database.json --wait
103+
```
104+
105+
## Using with Docker
75106

76-
# Direct API access for any endpoint
77-
redisctl api cloud get /subscriptions/88449/databases
107+
```bash
108+
# Run commands directly with Docker
109+
docker run --rm \
110+
-e REDIS_CLOUD_API_KEY \
111+
-e REDIS_CLOUD_API_SECRET \
112+
ghcr.io/joshrotenberg/redisctl:latest \
113+
cloud subscription list
114+
115+
# Use local config file
116+
docker run --rm \
117+
-v ~/.config/redisctl:/root/.config/redisctl:ro \
118+
ghcr.io/joshrotenberg/redisctl:latest \
119+
database list
120+
121+
# Development environment with test cluster
122+
make docker-up # Start Redis Enterprise cluster
123+
make docker-cli # Interactive CLI session
124+
make docker-test # Run test suite
125+
make docker-down # Clean up
78126
```
79127

128+
See the [Docker documentation](https://joshrotenberg.com/redisctl/getting-started/docker.html) for advanced usage.
129+
80130
## Documentation
81131

82132
For comprehensive documentation including:

‎docs/src/SUMMARY.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
- [Installation](./getting-started/installation.md)
88
- [Configuration](./getting-started/configuration.md)
99
- [Quick Start](./getting-started/quickstart.md)
10+
- [Authentication](./getting-started/authentication.md)
11+
- [Shell Completions](./getting-started/shell-completions.md)
12+
- [Docker Development](./getting-started/docker.md)
1013

1114
# Redis Cloud Commands
1215

@@ -42,6 +45,7 @@
4245

4346
# Tutorials
4447

48+
- [Common Recipes](./tutorials/common-recipes.md)
4549
- [Managing Production Databases](./tutorials/production-databases.md)
4650
- [Setting Up Monitoring](./tutorials/monitoring.md)
4751
- [Disaster Recovery](./tutorials/disaster-recovery.md)

‎docs/src/getting-started/shell-completions.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Shell Completions
2+
3+
redisctl supports tab completion for all major shells. This guide shows how to install and configure completions for your shell.
4+
5+
## Generating Completions
6+
7+
First, generate the completion script for your shell:
8+
9+
```bash
10+
# Bash
11+
redisctl completions bash > redisctl.bash
12+
13+
# Zsh
14+
redisctl completions zsh > _redisctl
15+
16+
# Fish
17+
redisctl completions fish > redisctl.fish
18+
19+
# PowerShell
20+
redisctl completions powershell > redisctl.ps1
21+
22+
# Elvish
23+
redisctl completions elvish > redisctl.elv
24+
```
25+
26+
## Installing Completions
27+
28+
### Bash
29+
30+
```bash
31+
# Linux - User-specific
32+
redisctl completions bash > ~/.local/share/bash-completion/completions/redisctl
33+
34+
# Linux - System-wide (requires sudo)
35+
sudo redisctl completions bash > /usr/share/bash-completion/completions/redisctl
36+
37+
# macOS with Homebrew
38+
redisctl completions bash > $(brew --prefix)/etc/bash_completion.d/redisctl
39+
40+
# Reload your shell
41+
source ~/.bashrc
42+
# or start a new terminal
43+
```
44+
45+
### Zsh
46+
47+
```bash
48+
# Add to your fpath (usually in ~/.zshrc)
49+
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
50+
51+
# Create directory if needed
52+
mkdir -p ~/.zsh/completions
53+
54+
# Generate completion file
55+
redisctl completions zsh > ~/.zsh/completions/_redisctl
56+
57+
# Reload your shell
58+
source ~/.zshrc
59+
# or start a new terminal
60+
```
61+
62+
### Fish
63+
64+
```bash
65+
# Generate completion file
66+
redisctl completions fish > ~/.config/fish/completions/redisctl.fish
67+
68+
# Completions are loaded automatically in new shells
69+
# or reload current shell:
70+
source ~/.config/fish/config.fish
71+
```
72+
73+
### PowerShell
74+
75+
```powershell
76+
# Add to your PowerShell profile
77+
redisctl completions powershell >> $PROFILE
78+
79+
# Or save to a file and source it
80+
redisctl completions powershell > redisctl.ps1
81+
Add-Content $PROFILE ". $PWD\redisctl.ps1"
82+
83+
# Reload profile
84+
. $PROFILE
85+
```
86+
87+
### Elvish
88+
89+
```bash
90+
# Generate completion file
91+
redisctl completions elvish > ~/.elvish/lib/redisctl.elv
92+
93+
# Add to rc.elv
94+
echo "use redisctl" >> ~/.elvish/rc.elv
95+
96+
# Reload shell
97+
exec elvish
98+
```
99+
100+
## Testing Completions
101+
102+
After installation, test that completions work:
103+
104+
```bash
105+
# Type and press Tab
106+
redisctl <Tab>
107+
# Should show: api, auth, cloud, enterprise, profile, etc.
108+
109+
# Try sub-commands
110+
redisctl cloud <Tab>
111+
# Should show: database, subscription, user, etc.
112+
113+
# Try options
114+
redisctl --<Tab>
115+
# Should show: --help, --version, --profile, --output, etc.
116+
```
117+
118+
## Troubleshooting
119+
120+
### Completions Not Working
121+
122+
1. **Check shell configuration:**
123+
```bash
124+
# Bash - verify completion is enabled
125+
echo $BASH_COMPLETION_COMPAT_DIR
126+
127+
# Zsh - check fpath
128+
echo $fpath
129+
130+
# Fish - check completion directory
131+
ls ~/.config/fish/completions/
132+
```
133+
134+
2. **Reload your shell:**
135+
```bash
136+
# Option 1: Source config file
137+
source ~/.bashrc # or ~/.zshrc, etc.
138+
139+
# Option 2: Start new shell
140+
exec $SHELL
141+
142+
# Option 3: Open new terminal
143+
```
144+
145+
3. **Verify file permissions:**
146+
```bash
147+
# Check completion file exists and is readable
148+
ls -la ~/.local/share/bash-completion/completions/redisctl
149+
# or your shell's completion directory
150+
```
151+
152+
### Updating Completions
153+
154+
When updating redisctl, regenerate completions to get new commands:
155+
156+
```bash
157+
# Example for Bash
158+
redisctl completions bash > ~/.local/share/bash-completion/completions/redisctl
159+
source ~/.bashrc
160+
```
161+
162+
### Custom Completion Directories
163+
164+
If using non-standard directories:
165+
166+
```bash
167+
# Bash - add to .bashrc
168+
source /path/to/redisctl.bash
169+
170+
# Zsh - add to .zshrc
171+
fpath=(/path/to/completions $fpath)
172+
autoload -U compinit && compinit
173+
174+
# Fish - add to config.fish
175+
source /path/to/redisctl.fish
176+
```
177+
178+
## Tips
179+
180+
- **Auto-update completions:** Add completion generation to your dotfiles setup
181+
- **Multiple shells:** Generate completions for all shells you use
182+
- **Container usage:** Mount completion files when using Docker:
183+
```bash
184+
docker run -v ~/.local/share/bash-completion:/etc/bash_completion.d:ro ...
185+
```
186+
- **CI/CD:** Include completion generation in your deployment scripts
187+
188+
## See Also
189+
190+
- [Installation Guide](installation.md) - Installing redisctl
191+
- [Configuration](configuration.md) - Setting up profiles
192+
- [Quick Start](quickstart.md) - Getting started with redisctl

0 commit comments

Comments
 (0)