CLI Reference¶

Complete command-line interface reference for Plating, including all commands, options, and auto-detection behavior.

Commands Overview¶

plating [OPTIONS] COMMAND [ARGS]...

Commands:
  adorn     Create documentation templates for components
  plate     Generate documentation from templates
  validate  Validate generated documentation
  info      Show provider and registry information
  stats     Display registry statistics

Command Reference¶

plating adorn¶

Create documentation templates for components that don't have them.

plating adorn [OPTIONS]

Options: - --provider-name TEXT - Provider name (auto-detected if not specified) - --package-name TEXT - Package to search (searches all if not specified) - --component-type [resource|data_source|function|provider] - Component types to process (repeatable) - --output-dir PATH - Output directory for templates (default: .plating) - --templates-only - Only generate templates, skip discovery - --verbose - Enable verbose output - --help - Show help message

Examples:

# Adorn all components
plating adorn

# Adorn only resources
plating adorn --component-type resource

# Adorn multiple types
plating adorn --component-type resource --component-type data_source

# Specify package
plating adorn --package-name pyvider.aws

plating plate¶

Generate documentation from templates.

plating plate [OPTIONS]

Options: - --provider-name TEXT - Provider name (auto-detected if not specified) - --package-name TEXT - Package to search (searches all if not specified) - --component-type [resource|data_source|function|provider] - Component types to process (repeatable) - --output-dir PATH - Output directory (default: auto-detected or docs/) - --force - Overwrite existing files - --validate/--no-validate - Run validation after generation (default: validate) - --project-root PATH - Project root directory (auto-detected if not specified) - --generate-examples - Generate executable examples - --examples-dir PATH - Output directory for flat examples (default: examples/) - --grouped-examples-dir PATH - Output directory for grouped examples (default: examples/integration/) - --verbose - Enable verbose output - --help - Show help message

Examples:

# Generate all documentation
plating plate

# Generate with validation disabled
plating plate --no-validate

# Force overwrite existing files
plating plate --force

# Custom output directory
plating plate --output-dir ./documentation

# Generate executable examples
plating plate --generate-examples

plating validate¶

Validate generated documentation.

plating validate [OPTIONS]

Options: - --provider-name TEXT - Provider name (auto-detected if not specified) - --package-name TEXT - Package to search (searches all if not specified) - --component-type [resource|data_source|function|provider] - Component types to validate (repeatable) - --output-dir PATH - Documentation directory to validate (must exist) - --verbose - Enable verbose output - --help - Show help message

Note: The validate command operates on already-generated documentation files. Unlike plate, it does not support --project-root (the output directory must be explicitly provided or will default to docs/)

Examples:

# Validate all documentation
plating validate

# Validate specific directory
plating validate --output-dir ./documentation

# Validate only resources
plating validate --component-type resource

plating info¶

Show provider and registry information.

plating info [OPTIONS]

Options: - --provider-name TEXT - Provider name (auto-detected if not specified) - --package-name TEXT - Package to search (searches all if not specified) - --verbose - Enable verbose output - --help - Show help message

Examples:

# Show info for auto-detected provider
plating info

# Show info for specific provider
plating info --provider-name aws --package-name pyvider.aws

plating stats¶

Display detailed registry statistics.

plating stats [OPTIONS]

Options: - --package-name TEXT - Package to search (searches all if not specified) - --verbose - Enable verbose output - --help - Show help message

Examples:

# Show statistics for all packages
plating stats

# Show statistics for specific package
plating stats --package-name pyvider.aws

Global Options¶

These options can be used with any command:

--log-level [DEBUG|INFO|WARNING|ERROR] - Set logging level
--no-color - Disable colored output
--quiet - Suppress non-error output
--version - Show version and exit
--help - Show help message

Auto-Detection Behavior¶

Provider Name Auto-Detection¶

The CLI attempts to determine the provider name in this order:

1. Explicit Flag (Highest Priority)¶

plating adorn --provider-name my_provider

2. Configuration File¶

Checks pyproject.toml in the current directory:

[tool.plating]
provider_name = "my_provider"

3. Package Name Pattern¶

Extracts from package name if it follows conventions: - terraform-provider-{name} → Provider: {name} - {name}-provider → Provider: {name}

Example:

[project]
name = "terraform-provider-aws"  # Auto-detects: aws

4. Fallback¶

If none of the above work, you must specify --provider-name.

Package Name Auto-Detection¶

Determines which package to search for components:

1. Explicit Flag (Highest Priority)¶

plating adorn --package-name pyvider.components

2. Current Directory's Package¶

Reads from pyproject.toml:

[project]
name = "pyvider.components"  # Auto-detected

3. Fallback Behavior¶

If not specified: Searches ALL installed packages
This can be slow for large environments
Recommended: Always specify --package-name for better performance

Output Directory Auto-Detection¶

For `plating plate` Command¶

Explicit Flag:

plating plate --output-dir ./documentation

Auto-Detection Logic:
Searches for existing documentation directories in order of preference:
1. ./docs/ - If the directory already exists
2. ./documentation/ - If the directory already exists
3. ./doc/ - If the directory already exists
If no existing directory is found, creates and uses ./docs/

For `plating validate` Command¶

Uses the same logic as plate to find where documentation was generated.

Component Type Auto-Detection¶

Default Behavior¶

If not specified, operations apply to ALL component types:

plating adorn  # Adorns resources, data_sources, and functions

Explicit Selection¶

plating adorn --component-type resource
plating adorn --component-type resource --component-type function

Project Root Auto-Detection¶

Determines the project root for relative paths:

Detection Order:¶

Explicit Flag:

plating plate --project-root /path/to/project

Git Repository Root:

# Walks up from current directory to find .git/
/path/to/project/.git/  # Found → project root is /path/to/project/

Pyproject.toml Location:

# Walks up to find pyproject.toml
/path/to/project/pyproject.toml  # Found → project root is /path/to/project/

Current Directory:

Path.cwd()  # Fallback if no indicators found

Examples Directory Auto-Detection¶

For Generated Examples¶

When using --generate-examples:

Explicit Flags:

plating plate --generate-examples \
  --examples-dir examples/ \
  --grouped-examples-dir examples/integration/

Defaults:
Flat examples: ./examples/
Grouped examples: ./examples/

Auto-Detection in Action¶

Minimal Command (Maximum Auto-Detection)¶

# In a properly configured project directory:
cd terraform-provider-mycloud
plating adorn    # Auto-detects everything
plating plate    # Auto-detects everything

What Gets Auto-Detected:¶

✅ Provider name: mycloud (from package name)
✅ Package name: From pyproject.toml
✅ Output directory: ./docs/ (if exists)
✅ Component types: All types
✅ Project root: Git repository root

When to Specify Values¶

Provide explicit values when: 1. Auto-detection fails or gives wrong results 2. Working outside a project directory 3. Wanting different behavior than defaults 4. Performance optimization (e.g., specific package)

Full Explicit Command¶

plating adorn \
  --provider-name mycloud \
  --package-name pyvider.mycloud \
  --component-type resource \
  --output-dir ./templates/

plating plate \
  --provider-name mycloud \
  --package-name pyvider.mycloud \
  --output-dir ./docs/ \
  --component-type resource \
  --project-root /path/to/project/

Configuration Precedence¶

From highest to lowest priority:

Command-line flags (always wins)
Environment variables (if implemented)
pyproject.toml [tool.plating] section
Auto-detection from context
Built-in defaults

Debugging Auto-Detection¶

To see what values are being auto-detected:

# Verbose mode shows auto-detection process
plating adorn --verbose

# Debug logging for detailed information
plating plate --log-level DEBUG

Example output:

[DEBUG] Auto-detected provider name: mycloud
[DEBUG] Auto-detected package name: pyvider.mycloud
[DEBUG] Using output directory: ./docs/
[INFO] Starting adorn operation...

Best Practices¶

For Projects¶

Configure in pyproject.toml:

[tool.plating]
provider_name = "mycloud"
# Note: Other settings must use CLI flags

Follow naming conventions:
Package: terraform-provider-{name}
Or: pyvider.{name}
Use standard directory structure:
Documentation: docs/
Examples: examples/

For CI/CD¶

Always use explicit flags in CI/CD to ensure reproducibility:

- name: Generate Documentation
  run: |
    plating adorn --provider-name ${{ env.PROVIDER }} --package-name ${{ env.PACKAGE }}
    plating plate --provider-name ${{ env.PROVIDER }} --output-dir docs/

For Development¶

Use auto-detection for convenience during development:

# Quick iterations during development
plating adorn && plating plate

Limitations¶

Currently, only provider_name can be configured in pyproject.toml. Other settings like output_dir, component_types, and package_name for filtering must be provided as CLI flags.

Future versions may expand configuration file support.

CLI Reference¶

Commands Overview¶

Command Reference¶

plating adorn¶

plating plate¶

plating validate¶

plating info¶

plating stats¶

Global Options¶

Auto-Detection Behavior¶

Provider Name Auto-Detection¶

1. Explicit Flag (Highest Priority)¶

2. Configuration File¶

3. Package Name Pattern¶

4. Fallback¶

Package Name Auto-Detection¶

1. Explicit Flag (Highest Priority)¶

2. Current Directory's Package¶

3. Fallback Behavior¶

Output Directory Auto-Detection¶

For plating plate Command¶

For plating validate Command¶

Component Type Auto-Detection¶

Default Behavior¶

Explicit Selection¶

Project Root Auto-Detection¶

Detection Order:¶

Examples Directory Auto-Detection¶

For Generated Examples¶

Auto-Detection in Action¶

Minimal Command (Maximum Auto-Detection)¶

What Gets Auto-Detected:¶

When to Specify Values¶

Full Explicit Command¶

Configuration Precedence¶

Debugging Auto-Detection¶

Best Practices¶

For Projects¶

For CI/CD¶

For Development¶

Limitations¶

For `plating plate` Command¶

For `plating validate` Command¶