pcli/openspec/changes/archive/2026-02-11-replace-auth-with-api-key/specs/cli-commands/spec.md

MODIFIED Requirements

Requirement: Root command and global flags

The system SHALL provide a root command pcli that serves as the entry point. The root command SHALL register global flags: --format (string, default json, values json or table), --url (string, overrides PLANKA_URL), --api-key (string, overrides PLANKA_API_KEY), and --log-level (string, default warn, values debug, info, warn, error). The root command SHALL initialize the logger based on --log-level and configure it to write structured JSON to stderr. The root command SHALL validate that URL and API key are available (from flags or environment) before executing any subcommand.

Scenario: Display help

• WHEN pcli is run with no arguments or --help
• THEN the system SHALL display usage information listing all resource subcommands and global flags

Scenario: Invalid format flag

• WHEN --format is set to an unsupported value
• THEN the system SHALL print an error and exit with code 1

Scenario: Log level controls output

• WHEN --log-level=debug is set
• THEN DEBUG-level log entries SHALL appear on stderr
• AND stdout SHALL contain only the command's data output

Scenario: Missing API key

• WHEN neither PLANKA_API_KEY environment variable nor --api-key flag is provided
• THEN the system SHALL print an error indicating PLANKA_API_KEY must be set via --api-key flag or PLANKA_API_KEY environment variable
• AND the system SHALL exit with code 1