Inconsistent option names across commands (--by, -c, -g, --columns, etc.)

[AliiiBenn]

Description

xl commands use inconsistent option names for similar functionality. Users must remember different flags for each command (e.g., -c means columns in some commands, but column index in others; --by vs -c vs --columns).

Current State (Inconsistent)

Command	Group By Column	Count Column	Sort Column	Select Column
xl group	--by	N/A	N/A	N/A
xl count	N/A	--columns / -c	--sort	N/A
xl unique	N/A	-c, --columns	N/A	N/A
xl sort	N/A	N/A	--by	N/A
xl select	N/A	N/A	N/A	-c, --columns
xl stats	N/A	-c, --columns	N/A	N/A
xl filter	Implicit in condition	N/A	N/A	--columns
xl head	N/A	N/A	N/A	N/A

Examples of Inconsistency

Inconsistency 1: Group-By vs Sort

# Group uses --by
xl group sales.xlsx --by "Category" --aggregate "Sales:sum"

# Sort uses --by (consistent!)
xl sort sales.xlsx --by "Sales_sum" --order desc

# But filter uses implicit column reference
xl filter sales.xlsx "Category == 'A'"

Problem: Mix of explicit flags and implicit references

Inconsistency 2: Column Specification

# count uses --columns / -c
xl count sales.xlsx --columns "Category"

# unique uses --columns / -c
xl unique sales.xlsx -c "Category"

# select uses --columns / -c
xl select sales.xlsx -c "Category,Sales"

# stats uses -c
xl stats sales.xlsx -c "Sales"

# But group uses --by (not -c!)
xl group sales.xlsx --by "Category" --aggregate "Sales:sum"

Problem: Why does xl group use --by while others use -c or --columns?

Inconsistency 3: Limit Options

# head uses -n
xl head sales.xlsx -n 10

# filter uses --rows / -n
xl filter sales.xlsx "condition" --rows 10

# count lacks -n (see XL-006)
xl count sales.xlsx -c "Category" --sort count -n 10  # Error!

# group lacks --limit
xl group sales.xlsx --by "Category" --aggregate "Sales:sum" --limit 10  # Error!

Problem: Inconsistent limiting mechanisms

Inconsistency 4: Short Flags

# -s means sheet
xl head sales.xlsx -s DONNEES -n 10

# -s means select in some CLIs (not xl, but still confusing)

# -c means columns (most of the time)
xl count sales.xlsx -c "Category"

# But --by for group (no -b short flag?)
xl group sales.xlsx --by "Category"

Problem: No standardized short flag convention

Impact

User Confusion

Users must check --help for every command to remember the right flags:

# User tries:
xl group data.xlsx -c "Category"  # Natural, but fails!

# Must check help:
xl group --help
# Oh, it's --by, not -c

# Later tries:
xl count data.xlsx --by "Category"  # Natural extension, but fails!
# Must check help again:
# Oh, it's --columns, not --by

Learning Curve

New users cannot transfer knowledge between commands:

# Learned: xl head -n 10
# Tries: xl count -c "X" -n 10
# Fails: -n not supported in count (XL-006)

Script Fragility

Scripts break when copying patterns between commands:

# Pattern that works for count:
xl count data.xlsx -c "Category" --sort count

# User tries same pattern for group:
xl group data.xlsx -c "Category" --aggregate "Sales:sum"
# Fails: -c not valid for group

Proposed Standards

Option 1: Establish Convention (Preferred)

Define standard flags for common operations:

Operation	Long Flag	Short Flag	Commands Using It
Column(s)	--column / --columns	-c	all (group, count, unique, select, stats, sort)
Group By	--by	-b or -g	group, count
Limit	--limit	-n	all output commands
Sort	--sort	-s	group, count, unique
Order	--order	-o	sort
Sheet	--sheet	-S (capital)	all Excel commands
Output	--output	-o	all commands

Option 2: Aliases for Backwards Compatibility

Add aliases to existing commands:

# xl group accepts both:
xl group data.xlsx --by "Category"
xl group data.xlsx -c "Category"  # New alias

# xl count accepts both:
xl count data.xlsx --columns "Category"
xl count data.xlsx -c "Category"
xl count data.xlsx --by "Category"  # New alias

Option 3: Smart Flag Detection

Auto-detect flag intent (may be confusing):

# xl group detects -c is column specification
# Automatically maps to --by behavior

Recommendation: Don't do this - too confusing

Acceptance Criteria

Phase 1: Documentation (Quick Win)

• Document all flags in comparison table
• Add "Common Patterns" section to help
• Show flag equivalents across commands
• Add "Did you mean?" suggestions for common mistakes

Phase 2: Standardization (Medium Effort)

• -c means "column(s)" everywhere
• -n means "limit" everywhere
• --by means "group by" (or use -b)
• Add -b short flag for --by
• Add -g short flag for --by (group)

Phase 3: Backwards Compatibility (Long Term)

• Support both old and new flags
• Emit deprecation warnings for old flags
• Document migration path
• Remove old flags after 2-3 version cycles

Test Cases

# Test 1: -c works for all column specifications
xl group data.xlsx -c "Category" --aggregate "Sales:sum"  # New
xl count data.xlsx -c "Category"  # Existing
xl unique data.xlsx -c "Category"  # Existing
# Expected: All work

# Test 2: -n works for all limits
xl head data.xlsx -n 10  # Existing
xl count data.xlsx -c "Category" -n 10  # New (XL-006)
xl group data.xlsx -c "Category" --aggregate "Sales:sum" -n 10  # New
# Expected: All work

# Test 3: -b works for group-by
xl group data.xlsx -b "Category" --aggregate "Sales:sum"  # New short flag
xl count data.xlsx -b "Category"  # New alias for --columns
# Expected: Both work

# Test 4: Backwards compatibility
xl group data.xlsx --by "Category" --aggregate "Sales:sum"  # Old
xl group data.xlsx -c "Category" --aggregate "Sales:sum"  # New
# Expected: Both work, same result

Proposed Flag Reference

Standard Column Flags

# Single column
-c COLUMN
--column COLUMN

# Multiple columns
-c COL1,COL2,COL3
--columns COL1,COL2,COL3

Used in: group, count, unique, select, stats, sort, filter

Standard Group-By Flags

# Single group
--by COLUMN
-b COLUMN  # New short flag

# Multiple groups
--by COL1,COL2,COL3
-b COL1,COL2,COL3  # New short flag

Used in: group, aggregate

Standard Limit Flags

-n ROWS
--limit ROWS

Used in: head, count, group, unique, filter

Standard Sort Flags

--sort [asc|desc]
-s [asc|desc]  # New short flag (not to conflict with --sheet)

Used in: group, count, unique, sort

Implementation Notes

Deprecation Strategy

Version N+0: Add new flags alongside old flags

xl group data.xlsx --by "Category"  # Old
xl group data.xlsx -c "Category"   # New
# Both work, no warning

Version N+1: Add deprecation warnings

xl group data.xlsx --by "Category"
# Warning: --by is deprecated, use -c or --column instead
# Will be removed in version N+3

Version N+2: Remove old flags

xl group data.xlsx --by "Category"
# Error: Unknown option: --by
# Use -c COLUMN or --column COLUMN

Short Flag Conflicts

Issue: -s currently means --sheet

Solution:

• Keep -s for --sheet (most common use case)
• Use -S (capital) for --sort
• Or use -s for --sort and change --sheet to --sh? No, too confusing

Recommendation:

• -s = --sheet (keep existing)
• No short flag for --sort (use long form only)
• Or use --sort only (no short flag needed)

Related Issues

• XL-006: xl count lacks -n (inconsistent limit option)
• XL-003: xl group lacks sort (inconsistent sorting)
• XL-009: Unclear pivot syntax (inconsistent aggregation)

Benefits

1. Learnability: Once users learn -c, it works everywhere
2. Memorability: Fewer flags to remember
3. Transferability: Patterns work across commands
4. Reduced Help Lookups: Don't need to check --help constantly
5. Better UX: Feels like a cohesive toolset

Industry Standards

git

git commit -m "msg"  # -c for commit (different meaning)
git checkout -b branch  # -b for branch

git has consistent conventions across subcommands

SQL

GROUP BY column
ORDER BY column

SQL uses textual keywords, not flags

pandas

df.groupby('column')  # Consistent method names
df.sort_values('column')
df[['col1', 'col2']]  # Consistent column selection

pandas is very consistent

Recommendation: Follow pandas' consistency example

Labels

design ux consistency medium-priority documentation standards

[AliiiBenn]

Implemented in v0.5.0 - Added -c alias for --by in xl group and created comprehensive OPTION_STANDARDS.md documentation. See release notes: https://github.com/AliiiBenn/excel-toolkit/releases/tag/v0.5.0