This document provides context for AI assistants (like Claude) working on this project.
CIDR is a command-line tool written in Go for parsing CIDR subnet masks and checking IP address membership. It focuses on providing a beautiful, user-friendly experience with styled terminal output.
- Language: Go 1.25.3
- CLI Framework: Cobra - Command-line interface and flag parsing
- Styling: Lipgloss - Terminal output styling and colors
cidr/
├── main.go # Entry point - calls cmd.Execute()
├── cmd/
│ └── root.go # Cobra root command with all CLI logic
├── go.mod # Module definition (github.com/trahma/cidr)
├── go.sum # Dependency checksums
├── README.md # User-facing documentation
├── CLAUDE.md # This file - AI assistant context
└── .gitignore # Excludes binary and build artifacts
- Takes CIDR notation (e.g.,
192.168.1.0/24) - Displays network address, subnet mask, broadcast address
- Shows IP ranges (total and usable)
- Calculates host counts (total and usable)
- Checks if an IP belongs to CIDR range(s)
- Works with single CIDR or multiple from config file
- Visual indicators: ✓ (in range), ○ (not in range)
- Default location:
~/.cidr - Format: One CIDR per line
- Supports comments (lines starting with
#) - Can specify custom path with
--configflag
Current design:
cidr [CIDR]- Parse a CIDR (positional argument)cidr [CIDR] --check [IP]- Check IP against specific CIDRcidr --check [IP]- Check IP against config file CIDRs
Flags:
-c, --check- IP address to check-f, --config- Custom config file path-h, --help- Show help
- Title style: Bold cyan (#86) for section headers
- Label style: Bold magenta (#205) for field labels
- Value style: Light blue (#117) for values
- Success style: Bold green (#42) for positive results
- Error style: Bold red (#196) for errors
- Info style: Yellow (#226) for neutral info
- Dim style: Dark gray (#240) for config file indicator
- Help style: Italic gray (#243) for help hints
- Help hint appears once at the end of output
- Config file path shown in dark gray when loaded
- Clear visual hierarchy with colors and spacing
- Single help message regardless of output length
- All CLI logic in
cmd/root.go - Helper functions for IP calculations at bottom of file
- Styles defined as package-level variables
- Config loading returns both CIDRs and path for display
Main entry point that:
- Processes arguments and loads config if needed
- Shows config file indicator if loaded
- Routes to either IP checking or CIDR display
- Shows help hint at the end
Parses and displays information for a single CIDR:
- Network details
- IP ranges
- Host counts
Checks an IP against one or more CIDRs:
- Validates IP address
- Iterates through CIDRs
- Shows results with visual indicators
- Summary message
Loads CIDR ranges from config file:
- Returns: (cidrs, configPath, error)
- Skips empty lines and comments
- Supports custom config path via flag
getBroadcastIP()- Calculate broadcast addressgetFirstUsableIP()- First usable host IP (network + 1)getLastUsableIP()- Last usable host IP (broadcast - 1)getTotalHosts()- Total addresses in rangegetUsableHosts()- Usable hosts (total - 2)
- Published on GitHub:
github.com/trahma/cidr - Installable via:
go install github.com/trahma/cidr@latest - Binary name:
cidr - Installed to:
$GOPATH/bin(typically~/go/bin)
- Subcommand structure (
cidr parse,cidr check) - Auto-detection of input type (IP vs CIDR)
- IPv6 support improvements
- JSON output format option
- Batch processing mode
- Additional network calculations
- Is the current flag-based approach optimal?
- Should we use subcommands instead?
- Should we auto-detect IP vs CIDR arguments?
- Make changes to code
- Test with:
go build -o cidr . && ./cidr [args] - Update README if user-facing changes
- Update this file if design decisions change
- Commit with descriptive message
- Push to GitHub
# Parse CIDR
./cidr 192.168.1.0/24
# Check IP against CIDR
./cidr 192.168.1.0/24 --check 192.168.1.50
# Check IP against config
./cidr --check 192.168.5.10
# Large network
./cidr 10.0.0.0/8
# Help
./cidr --help- Binary is gitignored (
.gitignoreexcludes build artifacts) - All colors use ANSI color codes via Lipgloss
- IPv4 is primary focus, IPv6 support is basic
- Config file format is intentionally simple
- No external dependencies beyond Cobra and Lipgloss