Skip to main content

​
CLI Tools Reference

Calmo Local Bridge allows you to execute CLI commands on your local machine directly from Calmo conversations. This guide covers the available tools, common use cases, and best practices.

​
Available Tools

When connected via Local Bridge, Calmo has access to these command execution capabilities:

Execute Commands

Run any shell command on your local machine

Process Management

Start, monitor, and terminate long-running processes

File Operations

Read and interact with local files and directories

Interactive Input

Send input to running processes

​
Command Execution

​
How It Works

  1. You ask Calmo to run a command (e.g., “check the pods in the staging namespace”)
  2. Calmo formulates the appropriate command (kubectl get pods -n staging)
  3. The command appears in your bridge’s Pending Commands
  4. You approve or deny the command
  5. Results stream back to Calmo in real-time

​
Basic Examples

Infrastructure Operations 
# Check Kubernetes resources
kubectl get pods -n production
kubectl describe deployment api-server
kubectl logs my-pod-abc123 --tail=100

# View cluster status
kubectl get nodes
kubectl top pods -n monitoring
Development Workflows 
# Git operations
git status
git log --oneline -10
git diff HEAD~1

# Package management
npm install
pip install -r requirements.txt
pnpm build
System Administration 
# File system operations
ls -la /path/to/project
cat config.yaml
find . -name "*.log" -mtime -1

# Process inspection
ps aux | grep node
docker ps

​
Common Use Cases

​
Kubernetes Troubleshooting

When investigating pod issues, Calmo can help by running diagnostic commands:
1

Check Pod Status

kubectl get pods -n chimnie
Calmo identifies pods in CrashLoopBackOff or Error state.
2

Describe Problem Pods

kubectl describe pod litellm-c8674ff77-tngdc -n chimnie
Gets detailed information about events and conditions.
3

View Container Logs

kubectl logs litellm-c8674ff77-tngdc -n chimnie
Retrieves logs to identify the root cause.
4

Apply Fix (if needed)

kubectl delete pod postgres-0 -n chimnie
Higher-risk operations require explicit approval.

​
Development Environment Setup

# Clone and setup a project
git clone https://github.com/org/repo.git
cd repo
npm install
npm run dev

​
Infrastructure as Code

# Terraform operations
terraform init
terraform plan
terraform apply -auto-approve

# Kustomize
kustomize build overlays/staging | kubectl apply -f -

​
Log Analysis

# Search logs for errors
kubectl logs deployment/api -n production | grep -i error

# Tail logs in real-time
kubectl logs -f pod/api-server-abc123 -n production

# Get logs from multiple containers
kubectl logs pod/my-pod -c init-container -n staging

​
Risk Levels

Commands are classified by risk level to help you make informed approval decisions:

​
Low Risk (Green)

Safe read operations that don’t modify state:
Command PatternDescription
kubectl get *List Kubernetes resources
kubectl describe *Describe resource details
kubectl logs *View container logs
git statusCheck repository status
ls, cat, pwdFile system reads
docker psList containers
Consider adding low-risk patterns to your Always Allow list to streamline your workflow.

​
Medium Risk (Yellow)

Write operations that modify state but are generally reversible:
Command PatternDescription
kubectl delete pod *Delete pods (will recreate)
kubectl scale *Scale deployments
git commitCreate commits
npm installModify dependencies
docker stop *Stop containers

​
High Risk (Red)

Operations that can cause significant impact:
Command PatternDescription
kubectl delete deployment *Delete deployments
kubectl delete pvc *Delete persistent storage
terraform destroyDestroy infrastructure
rm -rf *Recursive delete
kubectl apply *Apply configuration changes
Always carefully review high-risk commands. Consider the blast radius and whether you have backups or rollback plans.

​
Working Directory

Commands execute in the context of your Local Workspaces. If you’ve added /Users/pankaj/local_code/frontend as a workspace, Calmo can:
  • Navigate within that directory
  • Execute commands relative to that path
  • Access files and configuration within the workspace
Configure workspaces in the Workspaces tab to give Calmo appropriate context.

​
Long-Running Processes

The bridge supports long-running processes like development servers: 
# Start a development server
npm run dev

# Run a build in watch mode
tsc --watch

# Port forward a Kubernetes service
kubectl port-forward svc/api 8080:80 -n staging
Managing Long-Running Processes:
  • Calmo can start processes that continue running
  • Output streams back in real-time
  • You can ask Calmo to terminate processes when done
  • Process state persists until explicitly stopped

​
Interactive Commands

For commands requiring input: 
# Database CLI
psql -h localhost -U postgres

# Interactive prompts
npm init
Calmo can send input to these processes through the Pipe Process Input capability.

​
Environment & Shell

Commands run in your user’s shell environment:
  • macOS/Linux: Uses your default shell (bash, zsh)
  • Windows: Uses cmd.exe or PowerShell
  • Environment variables from your shell profile are available
  • PATH and other configurations are inherited

​
Command Output

Command output is:
  • Streamed in real-time to the Calmo conversation
  • Logged in the bridge’s Activity Log
  • Stored in command history with execution status
Large outputs may be truncated in the conversation but full output is available in the logs.

​
Best Practices

​
1. Use Specific Commands

Instead of broad operations, use targeted commands: 
# Good: Specific and safe
kubectl logs deployment/api -n staging --tail=50

# Avoid: Unbounded output
kubectl logs deployment/api -n staging

​
2. Preview Before Applying

For infrastructure changes: 
# First, preview
terraform plan
kubectl diff -f manifest.yaml

# Then apply
terraform apply
kubectl apply -f manifest.yaml

​
3. Scope Operations

Limit scope to reduce risk: 
# Good: Namespaced
kubectl get pods -n specific-namespace

# Risky: All namespaces
kubectl get pods -A

​
4. Use Dry-Run When Available

kubectl apply -f deployment.yaml --dry-run=client

​
Troubleshooting

​
Command Not Found

If commands fail with “command not found”:
  • Ensure the tool is installed on your local machine
  • Check if it’s in your PATH
  • Try using the full path to the executable

​
Permission Denied

If commands fail with permission errors:
  • Commands run with your user permissions
  • Some operations may require sudo (use with caution)
  • Check file/directory permissions

​
Timeout Issues

For commands that take too long:
  • Some commands have built-in timeouts
  • Long-running processes should be started appropriately
  • Check network connectivity for remote operations
For assistance with CLI tools, contact our support team at [email protected].