Skip to main content

Scripts

This repository contains various utility scripts for development, testing, and operations across multiple directories.

Script Locations​

DirectoryPurpose
/scriptsRoot-level utility scripts
/backstage/scriptsBackstage testing and debugging
/.specify/scriptsFeature development workflow

Root-Level Scripts (/scripts)​

access-vault-via-iap.sh​

Creates an IAP tunnel to the Vault instance for secure access.

./scripts/access-vault-via-iap.sh

Purpose: Set up secure access to Vault through Google Cloud's IAP Requirements: gcloud CLI, GCP project access

sync-vault-groups.sh​

Syncs GitHub Teams to Vault Identity Groups for JWT authentication.

# Interactive setup
./scripts/sync-vault-groups.sh setup

# Synchronize teams
./scripts/sync-vault-groups.sh sync

# List current groups
./scripts/sync-vault-groups.sh list

Commands:

  • setup - Interactive authentication setup
  • sync - Synchronize teams (default)
  • list - List current Vault groups

Requirements: gh CLI, gcloud CLI, vault CLI, jq

Backstage Scripts (/backstage/scripts)​

Testing Scripts​

test-claude-flow-integration.sh​

Validates complete Claude Flow plugin integration.

cd backstage
./scripts/test-claude-flow-integration.sh

Checks:

  • Plugin builds (frontend and backend)
  • TypeScript compilation
  • Linting (ESLint)
  • Unit tests
  • API structure
  • Component integration

test-tfc-integration.sh​

Comprehensive test suite for Terraform Cloud integration with Vault.

cd backstage
./scripts/test-tfc-integration.sh [--quick]

Options:

  • --quick - Skip TFC API test for faster validation

Tests:

  • Vault connection
  • JWT token creation
  • Backend health check
  • Token retrieval
  • Organization tokens
  • TFC API validation

Catalog Query Scripts​

query-catalog.sh​

Simple catalog entity query using JWT token.

cd backstage
./scripts/query-catalog.sh

Output: Entity counts grouped by Terraform workspace

search-catalog.sh​

Advanced catalog search with flexible options.

cd backstage
./scripts/search-catalog.sh [OPTIONS] [QUERY]

Options:

  • --token FILE - JWT token file
  • --backend URL - Backend URL (default: http://localhost:7007)
  • --verbose, -v - Verbose output

Exit Codes:

  • 0: Success
  • 1: Invalid arguments
  • 2: 4xx HTTP error
  • 3: 5xx HTTP error
  • 4: Connection error
  • 5: Invalid JSON

Token Management Scripts​

decode-service-token.js​

Decodes Backstage service-to-service JWT tokens.

cd backstage
node scripts/decode-service-token.js

Output: Header, payload claims, expiration info

setup-tfc-token.sh​

Sets up Terraform Cloud tokens in Vault.

cd backstage
./scripts/setup-tfc-token.sh

Features:

  • Interactive setup wizard
  • Token validation against TFC API
  • Vault KV storage

Documentation Scripts​

docscript.sh​

Generates Docusaurus documentation for organization repositories.

cd backstage
./scripts/docscript.sh [REPO_NAME]

Features:

  • Repository cloning
  • AI-assisted documentation planning
  • Docusaurus structure generation

Spec-Driven Development Scripts (/.specify/scripts)​

common.sh​

Shared utility functions for all .specify scripts.

Functions:

  • get_repo_root() - Find repository root
  • get_current_branch() - Get current branch
  • check_feature_branch() - Validate branch naming
  • get_feature_paths() - Export feature paths

setup-plan.sh​

Sets up implementation plan for a feature.

./.specify/scripts/bash/setup-plan.sh [--json]

Output: Feature spec path, plan path, specs directory

create-new-feature.sh​

Creates a new feature branch and specification directory.

./.specify/scripts/bash/create-new-feature.sh [OPTIONS] <description>

Options:

  • --json - JSON output
  • --short-name <name> - Custom branch name
  • --number N - Specific feature number

Example:

./create-new-feature.sh "Add user authentication" --short-name "user-auth"

check-prerequisites.sh​

Validates feature development prerequisites.

./.specify/scripts/bash/check-prerequisites.sh [OPTIONS]

Options:

  • --json - JSON output
  • --require-tasks - Require tasks.md
  • --include-tasks - Include tasks in output
  • --paths-only - Output paths only

update-agent-context.sh​

Updates AI agent context files with feature information.

./.specify/scripts/bash/update-agent-context.sh [agent_type]

Supported Agents: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q

Common Workflows​

Starting a New Feature​

# Create feature branch
./.specify/scripts/bash/create-new-feature.sh "My new feature"

# Set up plan
./.specify/scripts/bash/setup-plan.sh

# Check prerequisites
./.specify/scripts/bash/check-prerequisites.sh

# Update agent context
./.specify/scripts/bash/update-agent-context.sh claude

Testing Backstage Plugins​

cd backstage

# Test Claude Flow
./scripts/test-claude-flow-integration.sh

# Test TFC integration
./scripts/test-tfc-integration.sh

# Query catalog
./scripts/search-catalog.sh "kind=Resource"

Vault Operations​

# Access Vault via IAP
./scripts/access-vault-via-iap.sh

# Sync GitHub teams
./scripts/sync-vault-groups.sh sync

# Set up TFC token
cd backstage && ./scripts/setup-tfc-token.sh