Skip to main content

Managing Revisions

Castlecraft Architect provides several ways to manage revisions, catering to different workflows and operational modes. The primary tool for direct interaction and automation is the architect CLI.

Managing Revisions with the CLI​

The architect revision command group is your main entry point for managing revisions directly on your filesystem or within a CI/CD pipeline.

Usage:

$ architect revision [OPTIONS] COMMAND [ARGS]...

Common Options:

  • --help: Show help for the revision command group or a specific subcommand.

Applying Revisions from a File​

The apply-revision-file command is crucial for GitOps workflows or when you have a revision defined in a JSON file (e.g., downloaded from the Architect UI in Collaboration Mode).

Usage:

$ architect revision apply-revision-file [OPTIONS] OPERATIONS_FILE

Arguments:

  • OPERATIONS_FILE: Path to the JSON file containing the list of component operations. Options:
  • --dry-run: Simulate application and show intended changes without executing.

This command processes the specified JSON file and applies the component operations, generating or modifying code in your COMPONENTS_BASE_PATH.

Listing Available Revisions​

To see all revisions that have been previously applied or are available locally (typically stored in the .blocks directory within your project):

Usage:

$ architect revision list-revisions [OPTIONS]

This will output a list of revision IDs.

Getting the Last Applied Revision​

To quickly find out the ID of the most recently applied revision:

Usage:

$ architect revision get-last-applied [OPTIONS]

Applying an Existing Revision by ID​

If you know the ID of a revision (e.g., from list-revisions) and want to re-apply it or apply a specific version:

Usage:

$ architect revision apply-revision [OPTIONS] REVISION_ID

Arguments:

  • REVISION_ID: The ID of the revision to apply. Options:
  • --dry-run: Simulate application and show intended changes without executing.

Describing a Revision​

To inspect the contents (component operations) of a specific revision:

Usage:

$ architect revision describe-revision [OPTIONS] REVISION_ID

Arguments:

  • REVISION_ID: The ID of the revision to inspect.

Validating a Revision File​

Before applying a revision file, especially in automated contexts, you can validate its structure:

Usage:

$ architect revision validate-revision-file [OPTIONS] OPERATIONS_FILE

Arguments:

  • OPERATIONS_FILE: Path to the JSON file to validate.

Deleting Revisions​

You can manage locally stored revisions by deleting specific ones or cleaning up older ones.

Deleting a Specific Revision:

$ architect revision delete-revision [OPTIONS] REVISION_ID

Arguments:

  • REVISION_ID: The ID of the revision to delete.

Cleaning Up Older Revisions:

$ architect revision clean-revisions [OPTIONS]

Options:

  • -k, --keep INTEGER RANGE: Number of most recent revisions to keep (default: 3).

Local Revision Storage (CLI Mode)​

When using the CLI commands like apply-revision, list-revisions, etc., Architect typically stores revision data locally within your project, often in a directory named .blocks. Each applied revision's details are kept here, allowing you to list, describe, or re-apply them.

Managing Revisions via API (Collaboration Mode)​

In a "Collaboration Mode" setup (refer to Revision Workflows in Concepts), revisions are managed more formally:

  • /v1/ API: These RESTful API endpoints are used for creating "Revision Drafts," managing their lifecycle (e.g., approval), and potentially triggering the application of an "Approved Revision." These operations are typically backed by a database (like PostgreSQL) and integrate with authentication and authorization systems.
  • UI: The Architect web UI interacts with the /v1/ API to provide a user-friendly way for domain experts and developers to create and manage revision drafts.

Direct API Access (/internal/)​

Architect also exposes /internal/ API endpoints. These endpoints often mirror the functionality of the architect revision CLI commands and are intended for direct, local use or in trusted environments (like the Single User Mode). In Collaboration Mode, these /internal/ routes should generally not be exposed publicly due to potential security implications, as they might bypass more formal review and authorization processes.

Using UI​

The User interface us built on react and uses /v1/ api which will respect authentication and authorization if enabled.