CLI Getting Started

The Shoehorn CLI provides command-line access to the platform for browsing the catalog, managing governance actions, viewing GitOps resources, running Forge workflows, managing addons, and scripting automation.

Installation

Install using one of the following methods:

Homebrew (macOS / Linux):

brew tap shoehorn-dev/tap
brew install shoehorn

Mise (macOS / Linux / Windows):

# mise.toml or ~/.config/mise/config.toml
[tools."github:shoehorn-dev/shoehorn-cli"]
version = "latest"
exe = "shoehorn"

mise install

Go install:

go install github.com/shoehorn-dev/shoehorn-cli/cmd/shoehorn@latest

Scoop (Windows):

scoop bucket add shoehorn https://github.com/shoehorn-dev/scoop-bucket
scoop install shoehorn

Binary download: Download the latest release from GitHub Releases and add it to your PATH.

Verify the installation:

shoehorn version

Shell Completion

Set up tab-completion for your shell:

# Bash
shoehorn completion bash > /etc/bash_completion.d/shoehorn

# Zsh
shoehorn completion zsh > "${fpath[1]}/_shoehorn"

# Fish
shoehorn completion fish > ~/.config/fish/completions/shoehorn.fish

# PowerShell
shoehorn completion powershell > shoehorn.ps1

Authentication

PAT Authentication (Recommended)

Authenticate with a Personal Access Token generated from the Shoehorn web UI:

shoehorn auth login --server https://shoehorn.example.com --token shp_your_token

Secure token input (recommended for CI/CD and shared machines):

# Via environment variable (not visible in process listings)
export SHOEHORN_TOKEN=shp_your_token
shoehorn auth login --server https://shoehorn.example.com

# Via file
echo "shp_your_token" > ~/.shoehorn/token
export SHOEHORN_TOKEN_FILE=~/.shoehorn/token
shoehorn auth login --server https://shoehorn.example.com

Security note: The --token flag is visible in process listings (ps aux). Use SHOEHORN_TOKEN or SHOEHORN_TOKEN_FILE for CI/CD and shared machines.

Checking Auth Status

shoehorn auth status

Profile: default
Server:  https://shoehorn.example.com
Status:  Authenticated (PAT)
Email:   jane@example.com
Tenant:  acme-corp
Token:   Valid (PAT, no expiry)
Server:  Token verified with server

Logout

shoehorn auth logout

Note: Logout clears local credentials but does not revoke tokens server-side. If you suspect a token has been compromised, revoke it in the web UI under Settings > API Keys.

Configuration

The CLI configuration file supports multiple profiles:

~/.shoehorn/config.yaml

version: "1.0"
current_profile: default

profiles:
  default:
    name: Default
    server: https://shoehorn.example.com
    auth:
      provider_type: pat
      access_token: shp_xxxxxxxxxxxx
      user:
        email: jane@example.com
        name: Jane Smith
        tenant_id: acme-corp

  staging:
    name: Staging
    server: https://staging.shoehorn.example.com
    auth:
      provider_type: pat
      access_token: shp_stg_xxxx

Switch profiles per-command:

shoehorn --profile staging get entities
shoehorn --profile staging forge molds list

Quick Start

# Authenticate
shoehorn auth login --server https://shoehorn.example.com --token shp_xxxx

# Check who you are
shoehorn whoami

# Browse the catalog
shoehorn get entities
shoehorn search "payment"
shoehorn get entity payment-service --scorecard

# Run a workflow
shoehorn forge execute create-empty-github-repo \
  --input name=my-service --input owner=my-org

# Governance
shoehorn governance dashboard
shoehorn governance actions list

# Manage addons
shoehorn addon list
shoehorn addon browse
shoehorn addon install my-addon

# Validate manifests
shoehorn validate catalog-info.yaml
shoehorn convert catalog-info.yaml --to shoehorn

Available Commands

Catalog

shoehorn get entities                    # List all entities
shoehorn get entities --type service     # Filter by type
shoehorn get entity <id-or-slug>         # Entity details
shoehorn get entity <id> --scorecard     # With scorecard
shoehorn get teams                       # List teams
shoehorn get team <slug>                 # Team details + members
shoehorn get users                       # List users
shoehorn get user <id>                   # User details
shoehorn get groups                      # List groups
shoehorn get group <name>                # Group roles
shoehorn get molds                       # List Forge molds
shoehorn get mold <slug>                 # Mold details
shoehorn get runs                        # List Forge runs
shoehorn get run <id>                    # Run details
shoehorn get gitops                      # List GitOps resources
shoehorn get gitops --tool argocd        # Filter by tool
shoehorn get gitops <id>                 # GitOps resource details
shoehorn get owned --by team <slug>      # Entities owned by team
shoehorn get scorecard <entity-id>       # Scorecard breakdown
shoehorn get k8s                         # Kubernetes agents
shoehorn search "query"                  # Full-text search
shoehorn whoami                          # Your profile

Declarative Operations

shoehorn apply -f service.yaml             # Create or update
shoehorn apply -f catalog/                 # Apply all YAML in directory
shoehorn apply -f service.yaml --dry-run   # Preview changes
shoehorn diff -f service.yaml              # Show what apply would change
shoehorn diff -f catalog/                  # Diff entire directory

Write Operations

shoehorn create entity -f service.yaml    # Create from manifest
shoehorn update entity my-svc -f svc.yaml # Update from manifest
shoehorn delete entity my-svc             # Delete (with confirmation)
shoehorn delete entity my-svc --yes       # Delete (skip confirmation)

CI/CD Checks

shoehorn check scorecard my-svc --min-score 70  # Scorecard gate
shoehorn check entity my-svc --has-owner         # Quality gate
shoehorn check entity my-svc --has-owner -o json  # JSON for parsing

Governance

shoehorn governance actions list         # List all actions
shoehorn governance actions get <id>     # Action details
shoehorn governance actions create \     # Create action
  --entity-id "service:my-svc" \
  --title "Update docs" --priority high --source-type policy
shoehorn governance actions update <id> --status resolved  # Update
shoehorn governance actions delete <id> --yes              # Delete
shoehorn governance dashboard            # Health scores and metrics

Forge Workflows

shoehorn forge molds list                # Available templates
shoehorn forge molds get <slug>          # Template details
shoehorn forge execute <slug> \          # Execute workflow
  --input key=value --input key2=value2
shoehorn forge execute <slug> --dry-run  # Validate without executing
shoehorn forge run list                  # All runs
shoehorn forge run get <run-id>          # Run details

Addon Management

shoehorn addon list                      # Installed addons
shoehorn addon status <slug>             # Runtime status
shoehorn addon install <slug>            # Install
shoehorn addon uninstall <slug>          # Remove
shoehorn addon enable <slug>             # Enable
shoehorn addon disable <slug>            # Disable
shoehorn addon logs <slug>               # View logs
shoehorn addon browse                    # Browse marketplace

Addon Development

shoehorn addon init my-addon             # Scaffold new addon
shoehorn addon build                     # Build bundles
shoehorn addon build --dir ./my-addon    # Build from specific directory
shoehorn addon dev                       # Dev mode with hot reload
shoehorn addon publish --dir ./my-addon  # Publish to marketplace

Manifest Tools

shoehorn validate <file>                       # Validate Shoehorn/Backstage manifest
shoehorn validate <file> --format json         # JSON output for CI
cat manifest.yaml | shoehorn validate -        # Validate from stdin
shoehorn validate mold <file>                  # Validate Forge mold (offline)
shoehorn validate mold <file> --strict         # Fail on warnings too
shoehorn convert <file>                        # Convert formats
shoehorn convert <file> --to backstage         # To Backstage format
shoehorn convert <file> --to mold              # To Shoehorn Mold (JSON)
cat file.yaml | shoehorn convert -             # Convert from stdin
shoehorn convert ./dir -r                      # Recursive conversion

See the full CLI Validator reference for flag details, exit codes, and CI examples.

Global Flags

Flag	Short	Description
--output	-o	Output format: json, yaml, or table
--no-interactive	-I	Disable TUI, force plain text output
--interactive	-i	Force interactive TUI mode
--debug		Enable debug logging to stderr
--profile		Auth profile to use (default: default)
--config		Config file path (default: ~/.shoehorn/config.yaml)

Debug Mode

Enable debug logging to see HTTP requests, response codes, and timing:

shoehorn --debug get entities
# or
SHOEHORN_DEBUG=1 shoehorn get entities

Debug output goes to stderr so it won’t interfere with JSON/YAML piping:

shoehorn --debug get entities -o json 2>debug.log | jq .

Script-Friendly Output

Any command can be piped for automation:

shoehorn get entities -o json | jq '.[] | select(.type == "service") | .name'
shoehorn get team platform-team -o json | jq '.members[].email'
shoehorn whoami -o json | jq '.tenant_id'

Security

Token Storage

Tokens are stored in ~/.shoehorn/config.yaml with 0600 file permissions (owner-read/write only). The config file is saved atomically to prevent corruption. On POSIX systems, the CLI warns if file permissions have been loosened.

For enhanced security:

• Use SHOEHORN_TOKEN or SHOEHORN_TOKEN_FILE instead of --token flag
• Rotate tokens regularly via the web UI
• Use short-lived API keys with minimal scopes for CI/CD
• Ensure ~/.shoehorn/ is excluded from backup/sync tools