trustgraph/docs/cli/tg-delete-flow-blueprint.md

tg-delete-flow-blueprint

Permanently deletes a flow blueprint definition from TrustGraph.

Synopsis

tg-delete-flow-blueprint -n CLASS_NAME [options]

Description

The tg-delete-flow-blueprint command permanently removes a flow blueprint definition from TrustGraph. This operation cannot be undone, so use with caution.

⚠️ Warning: Deleting a flow blueprint that has active flow instances may cause those instances to become unusable. Always check for active flows before deletion.

Options

Required Arguments

• -n, --blueprint-name CLASS_NAME: Name of the flow blueprint to delete

Optional Arguments

• -u, --api-url URL: TrustGraph API URL (default: $TRUSTGRAPH_URL or http://localhost:8088/)

Examples

Delete a Flow Blueprint

tg-delete-flow-blueprint -n "old-test-flow"

Delete with Custom API URL

tg-delete-flow-blueprint -n "deprecated-flow" -u http://staging:8088/

Safe Deletion Workflow

# 1. Check if flow blueprint exists
tg-show-flow-blueprints | grep "target-flow"

# 2. Backup the flow blueprint first
tg-get-flow-blueprint -n "target-flow" > backup-target-flow.json

# 3. Check for active flow instances
tg-show-flows | grep "target-flow"

# 4. Delete the flow blueprint
tg-delete-flow-blueprint -n "target-flow"

# 5. Verify deletion
tg-show-flow-blueprints | grep "target-flow" || echo "Flow blueprint deleted successfully"

Prerequisites

Flow Blueprint Must Exist

Verify the flow blueprint exists before attempting deletion:

# List all flow blueprintes
tg-show-flow-blueprints

# Check specific flow blueprint
tg-show-flow-blueprints | grep "target-class"

Check for Active Flow Instances

Before deleting a flow blueprint, check if any flow instances are using it:

# List all active flows
tg-show-flows

# Look for instances using the flow blueprint
tg-show-flows | grep "target-class"

Error Handling

Flow Blueprint Not Found

Exception: Flow blueprint 'nonexistent-class' not found

Solution: Verify the flow blueprint exists with tg-show-flow-blueprints.

Connection Errors

Exception: Connection refused

Solution: Check the API URL and ensure TrustGraph is running.

Permission Errors

Exception: Access denied to delete flow blueprint

Solution: Verify user permissions for flow blueprint management.

Active Flow Instances

Exception: Cannot delete flow blueprint with active instances

Solution: Stop all flow instances using this class before deletion.

Use Cases

Cleanup Development Classes

# Delete test and development flow blueprintes
test_classes=("test-flow-v1" "dev-experiment" "prototype-flow")
for class in "${test_classes[@]}"; do
    echo "Deleting $class..."
    tg-delete-flow-blueprint -n "$class"
done

Migration Cleanup

# After migrating to new flow blueprintes, remove old ones
old_classes=("legacy-flow" "deprecated-processor" "old-pipeline")
for class in "${old_classes[@]}"; do
    # Backup first
    tg-get-flow-blueprint -n "$class" > "backup-$class.json" 2>/dev/null
    
    # Delete
    tg-delete-flow-blueprint -n "$class"
    echo "Deleted $class"
done

Conditional Deletion

# Delete flow blueprint only if no active instances exist
flow_class="target-flow"
active_instances=$(tg-show-flows | grep "$flow_class" | wc -l)

if [ $active_instances -eq 0 ]; then
    echo "No active instances found, deleting flow blueprint..."
    tg-delete-flow-blueprint -n "$flow_class"
else
    echo "Warning: $active_instances active instances found. Cannot delete."
    tg-show-flows | grep "$flow_class"
fi

Safety Considerations

Always Backup First

# Create backup before deletion
flow_class="important-flow"
backup_dir="flow-class-backups/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$backup_dir"

echo "Backing up flow blueprint: $flow_class"
tg-get-flow-blueprint -n "$flow_class" > "$backup_dir/$flow_class.json"

if [ $? -eq 0 ]; then
    echo "Backup created: $backup_dir/$flow_class.json"
    echo "Proceeding with deletion..."
    tg-delete-flow-blueprint -n "$flow_class"
else
    echo "Backup failed. Aborting deletion."
    exit 1
fi

Verification Script

#!/bin/bash
# safe-delete-flow-class.sh
flow_class="$1"

if [ -z "$flow_class" ]; then
    echo "Usage: $0 <flow-blueprint-name>"
    exit 1
fi

echo "Safety checks for deleting flow blueprint: $flow_class"

# Check if flow blueprint exists
if ! tg-show-flow-blueprints | grep -q "$flow_class"; then
    echo "ERROR: Flow blueprint '$flow_class' not found"
    exit 1
fi

# Check for active instances
active_count=$(tg-show-flows | grep "$flow_class" | wc -l)
if [ $active_count -gt 0 ]; then
    echo "ERROR: Found $active_count active instances using this flow blueprint"
    echo "Active instances:"
    tg-show-flows | grep "$flow_class"
    exit 1
fi

# Create backup
backup_file="backup-$flow_class-$(date +%Y%m%d-%H%M%S).json"
echo "Creating backup: $backup_file"
tg-get-flow-blueprint -n "$flow_class" > "$backup_file"

if [ $? -ne 0 ]; then
    echo "ERROR: Failed to create backup"
    exit 1
fi

# Confirm deletion
echo "Ready to delete flow blueprint: $flow_class"
echo "Backup saved as: $backup_file"
read -p "Are you sure you want to delete this flow blueprint? (y/N): " confirm

if [ "$confirm" = "y" ] || [ "$confirm" = "Y" ]; then
    echo "Deleting flow blueprint..."
    tg-delete-flow-blueprint -n "$flow_class"
    
    # Verify deletion
    if ! tg-show-flow-blueprints | grep -q "$flow_class"; then
        echo "Flow blueprint deleted successfully"
    else
        echo "ERROR: Flow blueprint still exists after deletion"
        exit 1
    fi
else
    echo "Deletion cancelled"
    rm "$backup_file"
fi

Integration with Other Commands

Complete Flow Blueprint Lifecycle

# 1. List existing flow blueprintes
tg-show-flow-blueprints

# 2. Get flow blueprint details
tg-get-flow-blueprint -n "target-flow"

# 3. Check for active instances
tg-show-flows | grep "target-flow"

# 4. Stop active instances if needed
tg-stop-flow -i "instance-id"

# 5. Create backup
tg-get-flow-blueprint -n "target-flow" > backup.json

# 6. Delete flow blueprint
tg-delete-flow-blueprint -n "target-flow"

# 7. Verify deletion
tg-show-flow-blueprints | grep "target-flow"

Bulk Deletion with Validation

# Delete multiple flow blueprintes safely
classes_to_delete=("old-flow1" "old-flow2" "test-flow")

for class in "${classes_to_delete[@]}"; do
    echo "Processing $class..."
    
    # Check if exists
    if ! tg-show-flow-blueprints | grep -q "$class"; then
        echo "  $class not found, skipping"
        continue
    fi
    
    # Check for active instances
    if tg-show-flows | grep -q "$class"; then
        echo "  $class has active instances, skipping"
        continue
    fi
    
    # Backup and delete
    tg-get-flow-blueprint -n "$class" > "backup-$class.json"
    tg-delete-flow-blueprint -n "$class"
    echo "  $class deleted"
done

Environment Variables

• TRUSTGRAPH_URL: Default API URL

Related Commands

• tg-show-flow-blueprints - List available flow blueprintes
• tg-get-flow-blueprint - Retrieve flow blueprint definitions
• tg-put-flow-blueprint - Create/update flow blueprint definitions
• tg-show-flows - List active flow instances
• tg-stop-flow - Stop flow instances

API Integration

This command uses the Flow API with the delete-class operation to remove flow blueprint definitions.

Best Practices

1. Always Backup: Create backups before deletion
2. Check Dependencies: Verify no active flow instances exist
3. Confirmation: Use interactive confirmation for important deletions
4. Logging: Log deletion operations for audit trails
5. Permissions: Ensure appropriate access controls for deletion operations
6. Testing: Test deletion procedures in non-production environments first

Troubleshooting

Command Succeeds but Class Still Exists

# Check if deletion actually occurred
tg-show-flow-blueprints | grep "deleted-class"

# Verify API connectivity
tg-show-flow-blueprints > /dev/null && echo "API accessible"

Permissions Issues

# Verify user has deletion permissions
# Contact system administrator if access denied

Network Connectivity

# Test API connectivity
curl -s "$TRUSTGRAPH_URL/api/v1/flow/classes" > /dev/null
echo "API response: $?"