feat: improve CLI argument parsing with subcommands and enhanced help text

[minhkhoango]

Summary

This PR improves the Phoenix CLI by reorganizing arguments into logical subcommands and adding comprehensive help text for better user experience.

Changes

• Added subcommands: serve, datasets, fixture, trace-fixture, demo
• Improved argument organization: Used ArgumentParser subparsers to group related arguments
• Enhanced help text: Added detailed descriptions and usage examples for each command
• Maintained compatibility: All existing functionality remains unchanged

Benefits

• Better UX: Users can now use phoenix <command> --help for specific help
• Clearer organization: Related arguments are grouped under logical subcommands
• Improved discoverability: Comprehensive help text makes the CLI more self-documenting
• Easier maintenance: Better structure makes it easier to add new commands in the future

Testing

• Verified all existing functionality works unchanged
• Tested help text for each subcommand
• Confirmed server starts correctly with new argument structure
• Validated that frontend builds and serves properly

Example Usage

# Get general help
phoenix --help

# Get help for specific command
phoenix serve --help
phoenix datasets --help
phoenix fixture --help

# Use new subcommand structure
phoenix serve --with-fixture=example
phoenix datasets --primary=example --reference=example
phoenix fixture example --primary-only

Breaking Changes

None - this is a backward-compatible enhancement.

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[minhkhoango]

I have read the CLA Document and I hereby sign the CLA

[RogerHYang]

Thank you for this PR! Could you help me understand the motivation for using conditional imports (i.e. using try/except) for the evals package?

[minhkhoango]

I use conditional imports for the evals package to support environments where it isn’t installed (e.g., local dev, lightweight installs). Without this, importing Phoenix can fail because Python resolves phoenix from the local src/phoenix/ directory first, which doesn’t include evals, causing ModuleNotFoundError.

The try/except pattern solves this by:

• Allowing core Phoenix functionality to import cleanly without evals
• Deferring failures until evals-specific features are actually used (with clear error messages)
• Supporting evals as an optional dependency while keeping install overhead low

This is a common Python pattern for optional dependencies and keeps the codebase flexible across dev and production environments.

[RogerHYang]

I use conditional imports for the evals package to support environments where it isn’t installed (e.g., local dev, lightweight installs). Without this, importing Phoenix can fail because Python resolves phoenix from the local src/phoenix/ directory first, which doesn’t include evals, causing ModuleNotFoundError.

The try/except pattern solves this by:

• Allowing core Phoenix functionality to import cleanly without evals
• Deferring failures until evals-specific features are actually used (with clear error messages)
• Supporting evals as an optional dependency while keeping install overhead low

This is a common Python pattern for optional dependencies and keeps the codebase flexible across dev and production environments.

Thanks for the extra context — that makes sense. The only catch is that evals is still a required dependency, and removing it would break some Phoenix features that rely on shared components. Since it’s not obvious how to make it optional just yet, would you mind reverting the import statements for now? We’d be happy to merge the rest of the PR!

[axiomofjoy]

Hey @minhkhoango, we really appreciate your interest in Phoenix and your desire to contribute. I do hear your desire to make the CLI more discoverable and ergonomic.

At the moment, only the serve command is intended to be user-facing. Other commands such as fixtures, trace-fixture, and demo are intended for internal usage only with our cloud platform. The datasets command is likely to be removed in a future release. For the various options that can be passed to the serve command, most of those such as --dev, --debug, and --read-only are intended for internal usage with our cloud platform or by our dev team, and --enable-websockets is no longer functional (dead code). There are a few arguments that are potentially user-facing, including --database-url, --host, --port, but these are legacy and have intentionally been hidden in order to encourage users to use the corresponding environment variables. This simplifies our documentation and makes it easier for us to troubleshoot issues. Really, the only user-facing API we've exposed in the CLI is phoenix serve, which is why our help menu is so sparse.

Perhaps you could help by letting us know what you found unintuitive about the current CLI and where we could improve short of exposing internal, non-user-facing APIs.

[minhkhoango]

I use conditional imports for the evals package to support environments where it isn’t installed (e.g., local dev, lightweight installs). Without this, importing Phoenix can fail because Python resolves phoenix from the local src/phoenix/ directory first, which doesn’t include evals, causing ModuleNotFoundError.
The try/except pattern solves this by:

• Allowing core Phoenix functionality to import cleanly without evals
• Deferring failures until evals-specific features are actually used (with clear error messages)
• Supporting evals as an optional dependency while keeping install overhead low

This is a common Python pattern for optional dependencies and keeps the codebase flexible across dev and production environments.

Thanks for the extra context — that makes sense. The only catch is that evals is still a required dependency, and removing it would break some Phoenix features that rely on shared components. Since it’s not obvious how to make it optional just yet, would you mind reverting the import statements for now? We’d be happy to merge the rest of the PR!

Thanks for clarifying! Totally makes sense about evals being a required dependency. I’ll revert the import changes and keep the rest of the PR intact. Appreciate the context — will push the update shortly.

[minhkhoango]

Hey @minhkhoango, we really appreciate your interest in Phoenix and your desire to contribute. I do hear your desire to make the CLI more discoverable and ergonomic.

At the moment, only the serve command is intended to be user-facing. Other commands such as fixtures, trace-fixture, and demo are intended for internal usage only with our cloud platform. The datasets command is likely to be removed in a future release. For the various options that can be passed to the serve command, most of those such as --dev, --debug, and --read-only are intended for internal usage with our cloud platform or by our dev team, and --enable-websockets is no longer functional (dead code). There are a few arguments that are potentially user-facing, including --database-url, --host, --port, but these are legacy and have intentionally been hidden in order to encourage users to use the corresponding environment variables. This simplifies our documentation and makes it easier for us to troubleshoot issues. Really, the only user-facing API we've exposed in the CLI is phoenix serve, which is why our help menu is so sparse.

Perhaps you could help by letting us know what you found unintuitive about the current CLI and where we could improve short of exposing internal, non-user-facing APIs.

Thanks for breaking that down — super helpful context. Before my changes, nearly all CLI help text was hidden via ==SUPPRESS==, so I surfaced it thinking it might improve discoverability. Now that I understand your focus on keeping the CLI minimal and internal, I’ll keep my changes focused on phoenix serve.

Quick feedback: the only friction point was seeing hidden commands/options without any hints. Would it be useful if I opened an issue summarizing first-time user pain points (without exposing internal APIs)?