deployment-management

name	deployment-management
description	Managing LangGraph Cloud deployments through listing, filtering, and cleanup operations. Use when managing test deployments, cleaning up orphaned resources, filtering by name patterns, or handling bulk deletion. Automatically sources credentials from devcontainer environment.
scope	project

Deployment Management

Manage LangGraph Cloud deployments using the Langstar CLI with focus on test deployment cleanup, filtering, and environment handling.

Core Capabilities

• List deployments with filtering by name, status, or type
• Filter test deployments by pattern (test-, langstar-test-)
• Delete deployments individually or in batch
• Handle environment variables automatically (check first, source if needed)
• Interactive confirmation for destructive operations

Table of Contents

• Prerequisites
• Environment Handling
• Core Workflows
• CLI Reference
• Best Practices
• Additional Resources

Prerequisites

Required Credentials

LangSmith API:

• LANGSMITH_API_KEY - API key for Control Plane authentication
• LANGSMITH_WORKSPACE_ID - Workspace ID (optional if using organization)

Location: /workspace/.devcontainer/.env (gitignored)

CLI Tool

All operations use langstar graph commands:

• langstar graph list - List with filtering
• langstar graph get <id> - Get details
• langstar graph delete <id> - Delete deployment

Environment Handling

Critical Pattern: Check Before Sourcing

Always check if credentials exist BEFORE sourcing:

# ✅ CORRECT: Check first
if [ -z "$LANGSMITH_API_KEY" ] || [ -z "$LANGSMITH_WORKSPACE_ID" ]; then
    echo "📋 Sourcing credentials..."
    source /workspace/.devcontainer/.env
fi

# Verify (never expose actual values)
[ -n "$LANGSMITH_API_KEY" ] && echo "✓ LANGSMITH_API_KEY set" || echo "❌ Not set"

Security Rule: Never expose credential values:

# ❌ WRONG: Exposes sensitive data
echo "Key: $LANGSMITH_API_KEY"

# ✅ CORRECT: Only check presence
[ -n "$LANGSMITH_API_KEY" ] && echo "Set" || echo "Not set"

Core Workflows

Workflow 1: List All Deployments

# Source credentials if needed
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# List deployments
langstar graph list --limit 20

Output:

┌────────────────────────────────┬──────────────────────┬────────┐
│ Name                           │ ID                   │ Status │
├────────────────────────────────┼──────────────────────┼────────┤
│ langstar-test-1763668434       │ 97dff6a5-f844-472... │ Ready  │
│ test-deployment-1763666536     │ 8665a96b-4620-407... │ Ready  │
└────────────────────────────────┴──────────────────────┴────────┘

Workflow 2: Filter by Name Pattern

# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# Filter by substring
langstar graph list --name-contains "test"
langstar graph list --name-contains "langstar-test"

# Combine filters
langstar graph list --name-contains "test" --status READY --limit 100

Workflow 3: Delete Single Deployment

# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# Interactive deletion (prompts for confirmation)
langstar graph delete <deployment-id>

# Skip confirmation
langstar graph delete <deployment-id> --yes

Workflow 4: Batch Cleanup of Test Deployments

Recommended: Interactive review before each deletion

# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# List test deployments to review
langstar graph list --name-contains "test" --limit 100

# Get deployment IDs
deployment_ids=$(langstar graph list --name-contains "test" --limit 100 --format json | jq -r '.resources[].id')

# Delete with confirmation for each
for id in $deployment_ids; do
    echo "Deployment: $id"
    langstar graph get "$id" | jq '{name, status, created_at}'
    read -p "Delete? (y/n): " confirm
    [ "$confirm" = "y" ] && langstar graph delete "$id" --yes && echo "✓ Deleted"
done

Alternative: Bulk deletion (use with caution)

See examples/batch-cleanup.md for non-interactive scripts.

Workflow 5: Filter by Status or Type

Available filters:

• Status: READY, AWAITING_DATABASE, UNUSED, AWAITING_DELETE
• Type: dev_free, dev, prod

# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# Filter by status
langstar graph list --status READY
langstar graph list --status UNUSED

# Filter by type
langstar graph list --deployment-type dev_free

# Combine filters
langstar graph list --name-contains "test" --status READY

CLI Reference

list - List deployments

langstar graph list [OPTIONS]

Options:
  -l, --limit <N>              Max to return [default: 20]
      --offset <N>             Pagination offset [default: 0]
      --name-contains <STR>    Filter by name substring
      --status <STATUS>        Filter: READY, AWAITING_DATABASE, UNUSED, etc.
      --deployment-type <TYPE> Filter: dev_free, dev, prod
  -f, --format <FORMAT>        Output: text, json [default: text]

get - Get deployment details

langstar graph get <DEPLOYMENT_ID>

Returns full deployment JSON including source config, status, timestamps, and revisions.

delete - Delete deployment

langstar graph delete <DEPLOYMENT_ID> [OPTIONS]

Options:
  -y, --yes    Skip confirmation prompt

Best Practices

Environment Variables

✅ Check before sourcing

if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

✅ Never expose values

[ -n "$LANGSMITH_API_KEY" ] && echo "✓ Set" || echo "✗ Not set"

Deployment Deletion

✅ Review before deleting

# List first, verify, then delete
langstar graph list --name-contains "test"
langstar graph delete <id> --yes

✅ Interactive confirmation for batch

# Confirm each deletion
for id in $ids; do
    read -p "Delete $id? (y/n): " confirm
    [ "$confirm" = "y" ] && langstar graph delete "$id" --yes
done

Filtering

✅ Use specific patterns

# Specific reduces false matches
langstar graph list --name-contains "langstar-test-"

✅ Combine filters for precision

langstar graph list --name-contains "test" --status READY --deployment-type dev_free

Common Use Cases

Clean Up After Integration Tests

# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi

# List test deployments
langstar graph list --name-contains "langstar-test"
langstar graph list --name-contains "test-deployment"

# Delete each
langstar graph delete <id-1> --yes
langstar graph delete <id-2> --yes

Find Unused Deployments

# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi

# List unused
langstar graph list --status UNUSED --limit 100

# Review and delete manually
langstar graph list --limit 100 --format json | \
    jq '.resources[] | select(.status == "UNUSED") | {name, id, created_at, status}'

Filter by User/CI Pattern

# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi

# Filter by username/CI prefix
langstar graph list --name-contains "alice-"
langstar graph list --name-contains "ci-build-"
langstar graph list --name-contains "pr-"

Troubleshooting

"Authentication failed"

Diagnosis:

[ -n "$LANGSMITH_API_KEY" ] && echo "Set" || echo "Not set"
[ -n "$LANGSMITH_WORKSPACE_ID" ] && echo "Set" || echo "Not set"

Solution:

source /workspace/.devcontainer/.env
# Verify
[ -n "$LANGSMITH_API_KEY" ] && echo "Set" || echo "Not set"

"Deployment not found"

Cause: Deployment deleted or incorrect ID.

Solution:

# Verify ID from list
langstar graph list --limit 100
langstar graph list --name-contains "<name-fragment>"

No Deployments Returned

Solution:

# Try without filters
langstar graph list --limit 100

# Try broader patterns
langstar graph list --name-contains "test"

Additional Resources

• Batch Cleanup Examples - Non-interactive deletion scripts
• CLI Command Reference - Detailed command documentation
• Issue #188 - Original feature request
• Issue #186 - Context for orphaned deployments
• SDK - sdk/src/deployments.rs - Full API client
• CLI - cli/src/commands/graph.rs - Implementation

Integration

With test-runner-worktree Skill

Clean up after test runs:

# After integration tests
cd /workspace/wip/<worktree-name>
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
langstar graph list --name-contains "langstar-test"

With git-worktrees Skill

Works in any location - credentials source the same:

# Works in main or worktree
cd /workspace
# or
cd /workspace/wip/claude-188-deployment-management

# Source once
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
langstar graph list

Quick Reference Templates

Environment Check

if [ -z "$LANGSMITH_API_KEY" ] || [ -z "$LANGSMITH_WORKSPACE_ID" ]; then
    source /workspace/.devcontainer/.env
fi
[ -n "$LANGSMITH_API_KEY" ] && echo "✓" || echo "✗"

List Test Deployments

if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
langstar graph list --name-contains "test" --limit 100

Interactive Batch Delete

if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
for id in $(langstar graph list --name-contains "test" --format json | jq -r '.resources[].id'); do
    langstar graph get "$id" | jq '{name, status, created_at}'
    read -p "Delete? (y/n): " confirm
    [ "$confirm" = "y" ] && langstar graph delete "$id" --yes
done

Key Takeaways

1. Check environment variables before sourcing
2. Never expose credential values
3. Review deployments before batch deletion
4. Use specific name patterns
5. Combine filters for precision
6. Interactive confirmation prevents accidents
7. CLI handles all operations - no direct API calls needed