Import from your own definition

Once you maintain your own modules, you can import a project type from a definition you control instead of the official library. This is the Praxis CLI path, raptor import project-type -f, and it covers the YAML format, module uploads, and private repositories. For the official library, see Import a project type.

Custom and blank definitions

Custom reads a YAML definition. The name comes from the file's name field, so the command takes no positional arguments:

raptor import project-type -f ./project-type.yml

Blank is a YAML with just two fields. It creates a type with no resource-type mappings, which the Control Plane treats as every module being allowed, the right sandbox for developing your own modules without mapping each one first:

name: my-project-type
description: What this project type is for

--managed facets/empty is not the same as a blank definition. It maps exactly the three cloud_account provider flavors, so a module you author later stays invisible in projects of that type until you map it with raptor create resource-type-mapping.

Metadata format

The project-type.yml file defines your project type configuration.

name: aws                          # Required. Project type name
description: AWS project type      # Required. Human-readable description

# Git template details. Only used with --include-base-template.
gitUrl: https://github.com/myorg/templates.git
gitRef: main
baseTemplatePath: project-types/aws/base

iacTool: TERRAFORM                 # Optional. TERRAFORM (default) or OPENTOFU
iacToolVersion: 1.5.7              # Optional. TERRAFORM must be 1.5.7; OPENTOFU must be 1.12.0 or higher (default 1.12.0)

allowedClouds:                     # Optional. Defaults to [AWS, AZURE, GCP, KUBERNETES]
  - AWS

modules:                           # Optional. IaC modules to include
  # Cloud Account Setup
  - intent: cloud_account
    flavor: aws_provider

  # Networking
  - intent: network
    flavor: aws_vpc

  # Kubernetes Cluster
  - intent: kubernetes_cluster
    flavor: eks

By default, project blueprints created from the type start from an empty template. Pass --include-base-template to use gitUrl, gitRef, and baseTemplatePath from the metadata instead, so new blueprints start with default resources. gitUrl and gitRef are required when the flag is set; baseTemplatePath stays optional and is only read then.

Importing from a private repository

If the base template lives in a private repository, pass a VCS account so the backend can authenticate:

# 1. Get your VCS account ID
raptor get accounts --type VERSION_CONTROL

# 2. Import using the VCS account for authentication
raptor import project-type -f ./project-type.yml \
  --include-base-template \
  --vcs-account-id <ACCOUNT_ID>

Public repositories need no VCS account.

Uploading IaC modules

The --modules-dir flag uploads the IaC modules listed in your metadata to the control plane, if they are not already there.

List modules in project-type.yml by intent and flavor (see the format above). You do not specify module paths.
Run import with --modules-dir:

raptor import project-type -f ./project-type.yml --modules-dir ./modules --outputs-dir ./outputs

Raptor then:
- Walks --modules-dir recursively and discovers each module by matching the intent and flavor in its facets.yaml.
- If --outputs-dir is provided, discovers and creates the output types the modules need before uploading them.
- Uploads each module with full validation and creates output types from output_interfaces and output_attributes.
- Reports success or failure for each module.

Example output:

Reading metadata from file: ./project-type.yml

Creating project type 'AWS' in Control Plane...

✓ Project type created successfully
  Name: AWS
  Description: AWS project type with common configurations
  ID: 691d8859a1985a048d8fef4f
  Template Path: project-types/aws/base

📦 Uploading IaC modules...

🔧 Creating output types...
  Creating output type @facets/aws_cloud_account...
  ✓ Created output type @facets/aws_cloud_account

  [1/3] Discovering module cloud_account/aws_provider...
  [1/3] Found at: aws/cloud_account/aws_provider/1.0
  [1/3] Uploading cloud_account/aws_provider...

=== Validating Module ===
✓ Checking facets.yaml...
✅ facets.yaml validated successfully
✓ Running terraform fmt...
🎨 Terraform files formatted
✓ Running terraform validate...
🔍 Terraform validation successful

=== Processing Outputs ===
✓ Found output_interfaces and/or output_attributes
✓ Generating output files...
✅ Generated output files: output-lookup-tree.json, output.facets.yaml

Uploading module cloud_account/aws_provider...
✓ Module uploaded successfully (ID: 691d9093a1985a048d8fef5c)

  [1/3] ✓ Uploaded cloud_account/aws_provider
  [2/3] Uploading network/aws_vpc...
  ...

📊 Module Upload Summary:
  ✓ Uploaded: 3
  ❌ Failed: 0

Example: a custom project type from a private repo with modules

# 1. Get your VCS account ID
raptor get accounts --type VERSION_CONTROL

# 2. Prepare the metadata file
cat > custom-type.yml <<EOF
name: internal-platform
description: Internal platform services
gitUrl: https://github.com/myorg/private-templates.git
gitRef: main
baseTemplatePath: templates/platform
allowedClouds:
  - AWS
  - GCP

modules:
  - intent: service
    flavor: standard
EOF

# 3. Import with modules
raptor import project-type -f custom-type.yml \
  --include-base-template \
  --vcs-account-id acc_xyz123 \
  --modules-dir ./local-modules \
  --outputs-dir ./local-outputs

Troubleshooting

Module validation fails with Terraform errors

Check the Terraform syntax in the failing module.
Ensure all required variables are present.
Run terraform validate locally in the module directory.

Upload manually with more control:

raptor create iac-module -f /path/to/module --skip-validation

Module conflicts with a built-in Facets module

Cannot update Facets built-in module with intent network and flavor aws_vpc.
Please choose a different flavor.

Use a different flavor name in your module's facets.yaml:

intent: network
flavor: aws_vpc_custom  # Changed from aws_vpc
version: 1.0

Output type creation fails

Ensure your module has proper output_interfaces and output_attributes in outputs.tf.

Create the output types manually:

raptor create output-type @custom/my-output -f output-schema.yaml

Use --dry-run to validate the schema file without creating anything:

raptor create output-type @custom/my-output -f output-schema.yaml --dry-run

Command reference

# List the managed project types the official library currently ships
raptor import project-type --list-managed

# Managed import from the official Facets library
raptor import project-type --managed facets/<name> [--name NAME]

# Custom import from a metadata file
raptor import project-type -f <METADATA_FILE>

# Include base template resources in new blueprints
raptor import project-type -f <METADATA_FILE> --include-base-template

# Import from a private repo
raptor import project-type -f <METADATA_FILE> \
  --include-base-template \
  --vcs-account-id <ACCOUNT_ID>

# Import a project type and upload modules not yet registered in the control plane
raptor import project-type -f <METADATA_FILE> \
  --modules-dir <MODULES_DIRECTORY> \
  --outputs-dir <OUTPUTS_DIRECTORY>

Flags:

-f, --file string             YAML metadata file with the project type configuration
    --list-managed            List managed project types available to import, then exit
    --managed string          Import an official Facets project type (format: facets/<name>; run --list-managed for the actual list)
    --name string             Override the project type name (works with --managed and --file)
    --include-base-template   Use gitUrl/gitRef/baseTemplatePath from the metadata for default blueprint resources
    --modules-dir string      Local directory containing IaC modules to upload (auto-set for --managed)
    --outputs-dir string      Local directory containing output type definitions (auto-set for --managed)
    --vcs-account-id string   VCS account ID for private repositories
    --useBranch               Enable git branch usage (default: true)
-o, --output string           Output format (table|wide|json|yaml)

FAQ

Do I need to specify the project type name in the command?

No. For custom imports the name is read from the YAML file's name field; for managed imports it comes from the library. Use --name to override it in either case.

Do I need to upload modules every time?

No. Already-uploaded modules are skipped. Use --modules-dir only when you want to upload new or updated modules.

What happens to existing projects when I update a project type?

Nothing. Project type updates only affect new projects created after the update.

Will re-importing merge into the existing module mappings?

No, it replaces them. Every import sends the complete definition, so re-importing a YAML whose modules: list is short or missing removes the mappings that are not in it, and an import with no modules: key at all turns a curated type into an unrestricted one and resets its base template to the default empty one. Keep the YAML you import as the full source of truth, and use raptor create resource-type-mapping / raptor delete resource-type-mapping for incremental changes.

Can I use modules from different project types?

Yes. Once modules are uploaded to the Control Plane, any project can use them, regardless of which project type imported them.

What if my module has custom dependencies?

Specify all Terraform dependencies in your module's Terraform configuration. Validation runs terraform init, which fetches the required providers and modules.

Import from your own definition

On this page