docs: add license command documentation and improve CLI command structure

[markphelps]

Summary

• Add documentation for new license check and license activate commands
• Structure license commands as subcommands (similar to config init/edit)
• Update quickstart command docs to describe new TUI features
• Add synopsis sections to all CLI commands for consistency
• Standardize command documentation order: Synopsis → Options → Examples
• Add license command references to licensing documentation
• Include quickstart command reference in quickstart guide

Changes

New Documentation

• Created docs/v2/cli/commands/license/check.mdx - documentation for checking license status
• Created docs/v2/cli/commands/license/activate.mdx - documentation for activating licenses

Updated Documentation

• Updated docs/v2/cli/commands/quickstart.mdx - added details about new TUI interface
• Updated docs/v2/licensing.mdx - added references to license CLI commands
• Updated docs/v2/quickstart.mdx - added tip about quickstart command
• Updated all CLI command docs to follow consistent Synopsis → Options → Examples structure

Navigation

• Updated docs/docs.json to include license command group with subcommands

Notes

Screenshot placeholders have been added with TODO comments for the following:

• License check output
• License activation wizard

Fixes #369

[claude]

Pull Request Review

I've reviewed PR #370 and overall this is excellent work! The documentation additions are well-structured, consistent, and follow the project's style guidelines. Here's my detailed feedback:

✅ Strengths

Documentation Quality

• Consistent structure: All CLI command docs now follow the Synopsis → Options → Examples pattern, which greatly improves readability and user experience
• Clear frontmatter: All new files include proper title and description fields as required
• Good use of markdown: Code blocks are properly tagged with bash, following the technical requirements
• Relative links: All internal links use relative paths (e.g., /v2/licensing, /v2/pro)
• User-focused content: The synopsis sections clearly explain what each command does and how it benefits users

Structural Improvements

• Proper grouping: The new license commands are correctly organized as a subgroup in docs.json, matching the pattern used by config commands
• Cross-referencing: Excellent integration between the new CLI commands and existing documentation (licensing.mdx, quickstart.mdx)
• Consistency: Updated all existing CLI commands to follow the same structure, not just the new ones

Writing Style

• Second-person voice: Consistently uses "you" and "your" throughout
• Clear and concise: Descriptions are developer-focused without unnecessary jargon
• Actionable examples: All commands include practical usage examples with the --config flag variant

📝 Minor Suggestions

1. License Command Descriptions (docs/v2/cli/commands/license/check.mdx & activate.mdx)

The descriptions use consistent formatting with bullet lists, which is great. However, consider these minor improvements:

In check.mdx (line 14-20), the list describes what the command does. Consider adding brief context about when a user might run this command:

## Synopsis

Validates your current license configuration and displays license status information.

Use this command to verify your license is properly configured before deploying to production, or to troubleshoot licensing issues.

The `check` command:

In activate.mdx (line 14-20), similar suggestion for clarity:

## Synopsis

Interactive wizard for activating a new Flipt Pro license.

Run this command when you first receive a license key or need to update your license configuration.

The `activate` command provides a guided, text-based user interface that:

2. Code Block Formatting Consistency

In docs/v2/cli/commands/evaluate.mdx (line 34), there's a blank line within the code block that might not be intentional:

flipt evaluate chat-enabled --context test=foo

{"flag_key":"chat-enabled",...}

This is fine if the output appears on a separate line, but verify this matches the actual command output.

3. Migration Command Note Placement

In docs/v2/cli/commands/migrate.mdx, the Note component now appears after the Synopsis section. Consider whether it should come before the synopsis since it's important context about when the command runs:

## Synopsis

<Note>
  This currently only supports Clickhouse analytics database migrations.
</Note>

Runs pending analytics database migrations.

This gives users the important limitation upfront.

4. Link Text in licensing.mdx

In docs/v2/licensing.mdx (lines 54-55), the link formatting follows the project guidelines perfectly. However, the bold formatting might be redundant with the backticks:

- [`flipt license check`](/v2/cli/commands/license/check): Validate your current license and view available Pro features
- [`flipt license activate`](/v2/cli/commands/license/activate): Interactive wizard to activate a new license

This is more of a stylistic preference, but consider removing the bold ** markers since the command is already in code format.

🔍 Questions/Clarifications

1. Screenshot TODOs

The PR description mentions "Screenshot placeholders have been added with TODO comments" for license check output and activation wizard. I don't see these TODO comments in the diff. Were they added in a different way, or should they be added to the MDX files?

If they need to be added, consider using HTML comments that won't render:

<!-- TODO: Add screenshot of license check output -->
<!-- TODO: Add screenshot of license activation wizard -->

2. Offline License Validation

In activate.mdx (line 17), it mentions "Handles online and offline license configurations". Should there be a note or example showing the difference between these two modes? This could be helpful for users in air-gapped environments.

3. More Info Links

In the new license command docs, the "More Info" section links to both /v2/licensing and /v2/pro. Consider whether both links are necessary, or if just linking to /v2/licensing is sufficient (since licensing.mdx already links to pro).

🎯 Testing Recommendations

Before merging, please verify:

1. Vale linting: Run vale docs/v2/cli/commands/license/*.mdx to ensure prose quality
2. Link validation: Verify all internal links resolve correctly with mint dev
3. Navigation: Test that the license command group appears correctly in the sidebar navigation
4. Formatting: Run npm run format to ensure consistent formatting

📊 Overall Assessment

Approval: ✅ Recommended for merge (after addressing minor suggestions)

This PR significantly improves the CLI documentation structure and adds valuable content for Pro license management. The changes are well-implemented, consistent with existing patterns, and follow the project's guidelines as outlined in CLAUDE.md.

Impact: High value - provides clear guidance for Pro users while improving overall CLI documentation consistency.

Risk: Low - documentation-only changes with no code modifications.

Great work on this comprehensive documentation update! 🎉

[markphelps]

@claude help me address the minor inconsistencies either on this branch or another one based off of this branch

[claude]

Claude finished @markphelps's task in 2m 11s —— View job

---

Addressing Minor Inconsistencies ✅

I've successfully addressed the minor suggestions from my previous review on this branch.

Changes Made

1. Enhanced license command context (check.mdx and activate.mdx)

   • Added contextual guidance about when to use each command
   • check.mdx: Added "Use this command to verify your license is properly configured before deploying to production, or to troubleshoot licensing issues."
   • activate.mdx: Added "Run this command when you first receive a license key or need to update your license configuration."

2. Improved Note placement (migrate.mdx)

   • Moved the Clickhouse limitation Note before the description for better visibility
   • Users now see the important limitation upfront before reading what the command does

3. Cleaned up link formatting (licensing.mdx)

   • Removed redundant bold markers from command links
   • Commands are already emphasized with backticks, so **bold** was unnecessary

4. Added screenshot placeholders

   • Added HTML comment TODOs for both license commands:
     • `` in check.mdx
     • `` in activate.mdx

5. Code block formatting (evaluate.mdx)

   • Reviewed and confirmed the blank line between command and output is intentional and correct

Tasks Completed

• Read current state of files to understand changes
• Add context to license command descriptions (check.mdx and activate.mdx)
• Review code block formatting in evaluate.mdx (looks good as-is)
• Adjust Note placement in migrate.mdx
• Clean up link formatting in licensing.mdx
• Add screenshot TODO comments
• Commit and push changes

Notes on Linting

I don't have permissions to run npm run format or vale commands, but the changes follow the existing patterns in the codebase and maintain consistency with the Microsoft Writing Style Guide. The automated Vale checks in the GitHub Actions workflow will catch any prose linting issues.

Commit

Changes committed and pushed to branch markphelps/update-license-quickstart-docs:

• Commit: 29d773b - "docs: address minor documentation inconsistencies"
• All changes follow the project's documentation standards from CLAUDE.md
• Used Conventional Commits format with proper co-authorship

--- |

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.