Validation Commands

Validation commands verify that your project conforms to FORGE conventions, API contracts, and template structure requirements. This group also covers secret management, API documentation generation, and CLI upgrade operations.

Validation

forge validate:api

Validate that the API implementation matches the defined contract. Checks route definitions, handler signatures, DTO structures, and response formats against the project's architecture contract.

forge validate:api

Example Output

Validating API contract...

  Routes:
    ✓ GET    /api/v1/contents
    ✓ POST   /api/v1/contents
    ✓ GET    /api/v1/contents/:id
    ✓ PUT    /api/v1/contents/:id
    ✓ DELETE /api/v1/contents/:id
    ✗ GET    /api/v1/lookups        (handler missing)

  DTOs:
    ✓ CreateContentRequest
    ✓ UpdateContentRequest
    ✗ CreateLookupRequest          (file missing)

Validation failed: 2 issues found.

forge validate:pages

Validate that the frontend pages match the expected route structure and component conventions.

forge validate:pages

Example Output

Validating pages...

  Admin:
    ✓ /dashboard
    ✓ /contents
    ✓ /contents/create
    ✓ /contents/[id]
    ✓ /contents/[id]/edit
    ✓ /users
    ✗ /lookups                     (page missing)

  Web:
    ✓ /
    ✓ /[slug]
    ✓ /profile

Validation failed: 1 issue found.

forge validate:template

Validate that the project's template structure is intact and all required files are present.

forge validate:template

forge validate:project

Run a comprehensive validation of the entire FORGE project against FORGE standards. Checks configuration, Docker setup, environment files, version control, and project structure in one pass.

forge validate:project [OPTIONS]

Option	Type	Default	Description
--path	string	.	Project directory to validate.
--format	string	text	Output format: text or json.

Example Output

Validating FORGE project...

  ✓ Configuration — forge.yaml found
  ✓ forge.yaml: project.name — Field present
  ✓ forge.yaml: project.backend — Field present
  ✓ Docker Setup — docker-compose.yaml found
  ✓ Environment — .env file found
  ✓ Version Control — Git repository initialized
  ✓ Git Ignore — .gitignore found

  Summary: 7 passed, 0 failed
All validations passed!

TIP

Run all four validation commands before deploying to catch structural issues early. They are fast and safe to run at any time.

---

Secret Management

forge secrets:generate-key

Generate a cryptographically secure secret key for JWT signing, encryption, or other application secrets.

forge secrets:generate-key [OPTIONS]

Option	Type	Default	Description
--output	string	.env	File to write the generated key to.

Example

forge secrets:generate-key --output=.env

Generated APP_SECRET_KEY and wrote to .env

forge secrets:encrypt

Encrypt a plaintext value using the project's encryption key (FORGE_ENCRYPTION_KEY from .env).

forge secrets:encrypt <VALUE> [OPTIONS]

Option	Type	Default	Description
--env-file	string	.env	Path to the .env file containing FORGE_ENCRYPTION_KEY.

Example

forge secrets:encrypt "my-secret-api-key"

Encrypting value...

  ✓ Value encrypted

  Encrypted value:
  enc:v1:abc123def456...

forge secrets:decrypt

Decrypt an encrypted value (prefixed with enc:v1:) using the project's encryption key.

forge secrets:decrypt <VALUE> [OPTIONS]

Option	Type	Default	Description
--env-file	string	.env	Path to the .env file containing FORGE_ENCRYPTION_KEY.

Example

forge secrets:decrypt "enc:v1:abc123def456..."

Decrypting value...

  ✓ Value decrypted

  Decrypted value:
  my-s****

WARNING

The decrypted value is partially masked for security. Use the decrypted output programmatically rather than displaying it in logs.

forge secrets:verify

Verify that all required secrets are present and correctly configured.

forge secrets:verify

Example Output

┌──────────────────────┬──────────┬────────────────────────────────┐
│ Secret               │ Status   │ Source                         │
├──────────────────────┼──────────┼────────────────────────────────┤
│ APP_SECRET_KEY       │ Set      │ .env                           │
│ DATABASE_URL         │ Set      │ .env                           │
│ REDIS_URL            │ Set      │ .env                           │
│ TWILIO_AUTH_TOKEN    │ Missing  │ Required by provider sms:twilio│
│ S3_SECRET_KEY        │ Set      │ .env                           │
└──────────────────────┴──────────┴────────────────────────────────┘

1 missing secret. Add TWILIO_AUTH_TOKEN to .env to resolve.

---

Upgrade Commands

Upgrade commands manage FORGE CLI and project version transitions, ensuring generated code stays compatible with the latest FORGE release.

forge upgrade:apply

Upgrade the current project's generated files to match the installed CLI version. FORGE compares the project's generated file hashes against the latest templates and applies updates.

forge upgrade:apply [OPTIONS]

Option	Type	Default	Description
--version	string	Latest	Target version to upgrade to.
--no-backup	flag	false	Skip creating a backup before upgrading.
--dry-run	flag	false	Show what would change without modifying any files.

Example Output

Upgrading project to forge 0.5.2...

  Modified files:
    api/src/main.rs               updated
    api/src/utils/response.rs     updated
    web/next.config.js            updated

  New files:
    api/src/middleware/cors.rs     created

  3 files updated, 1 file created.
  Run "forge validate:api" to verify the upgrade.

WARNING

forge upgrade:apply only modifies files originally generated by FORGE. It will not overwrite files you have manually edited. If a generated file has local modifications, FORGE creates a .forge-merge file for you to resolve manually.

forge upgrade:check

Check whether the current project needs any upgrades without making changes.

forge upgrade:check

Example Output

Current project version: 0.5.1
Installed CLI version:   0.5.2

3 files would be updated, 1 file would be created.
Run "forge upgrade" to apply changes.

forge upgrade:rollback

Roll back the most recent upgrade by restoring the previous versions of modified files.

forge upgrade:rollback

TIP

FORGE stores a backup of modified files before each upgrade. You can roll back safely, but only the most recent upgrade can be reversed.

forge upgrade:history

Display the upgrade history for the current project.

forge upgrade:history

Example Output

┌────┬─────────┬─────────┬─────────────────────┬───────────────┐
│ #  │ From    │ To      │ Date                │ Files Changed │
├────┼─────────┼─────────┼─────────────────────┼───────────────┤
│  1 │ 0.4.0   │ 0.4.1   │ 2025-02-15 10:30:00 │ 2             │
│  2 │ 0.4.1   │ 0.5.0   │ 2025-03-01 14:22:00 │ 12            │
│  3 │ 0.5.0   │ 0.5.1   │ 2025-03-20 09:15:00 │ 5             │
│  4 │ 0.5.1   │ 0.5.2   │ 2025-04-12 11:45:00 │ 4             │
└────┴─────────┴─────────┴─────────────────────┴───────────────┘

forge upgrade:lock

Initialize or regenerate the forge.lock file that tracks generated file checksums and upgrade history. This file is essential for the upgrade system to detect which files have been customized.

forge upgrade:lock [OPTIONS]

Option	Type	Default	Description
--force	flag	false	Regenerate the lock file even if one already exists.

Example Output

Generating forge.lock...
  [1/2] Scanning project files...
  [2/2] Writing forge.lock...

Generated forge.lock with 47 files tracked

  File breakdown:
    Core:      12
    Config:    5
    Template:  18
    Generated: 8
    User:      4

TIP

Always commit forge.lock to version control. It ensures every team member works with the same FORGE version context, and upgrades can be applied consistently.

---

See Also

• Project Commands — forge update updates the CLI itself
• Deployment Commands — validate before deploying
• Provider Commands — secrets:verify checks provider-specific secrets