Skip to main content

csh overview

The csh command provides Caeros Terminal's core command line interface, allowing users to interact with both terminal and graphical elements from the command line. This guide covers the basics of using csh and its key features.

See the csh reference for a list of all csh commands and their arguments.

Overview​

At its core, csh enables seamless interaction between your terminal commands and Caeros's graphical blocks. It allows you to:

  • Control graphical widgets directly from the command line
  • Share data between terminal sessions and GUI components
  • Manage your workspace programmatically
  • Connect remote and local environments
  • Send CLI output and files directly to AI conversations
  • Run terminal commands in separate, isolated blocks

Key Concepts​

Interacting with Blocks​

csh provides direct interaction with Caeros's graphical blocks through the command line. For example:

# Open a file in the editor
csh edit config.json

# Get the current file path from a preview block
csh getmeta -b 2 file

# Send output to an AI assistant (the "-" reads from stdin)
ls -la | csh ai - "what are the largest files here?"

Persistent State​

csh can maintain state across terminal sessions through its variable system:

# Store a variable that persists across sessions
csh setvar API_KEY=abc123

# Store globally
csh setvar DEPLOY_ENV=prod
# Or store in the current workspace
csh setvar -b workspace DEPLOY_ENV=staging

# Use stored variables in commands
curl -H "Authorization: $(csh getvar API_KEY)" https://api.example.com

Accessing Local Files from Remote​

When working on remote machines, you can access files on your local computer using the csh://local/~/ path prefix with csh file commands. The shorthand /~/ can also be used as an alias for csh://local/~/:

# Read a local file from a remote machine
csh file cat csh://local/~/config/app.json

# Run a local script on the remote machine using shell process substitution
bash <(csh file cat csh://local/~/scripts/deploy.sh)
python <(csh file cat csh://local/~/scripts/deploy.py)

# Append remote output to a local log file
echo "Remote machine log entry" | csh file append csh://local/~/app.log

# Copy a local file to the remote machine
csh file cp csh://local/~/data.csv ./remote-data.csv

# Copy remote file back to local machine
csh file cp ./results.txt csh://local/~/results.txt

# You can also use the shorthand /~/ instead of csh://local/~/
csh file cat /~/config/app.json

Block Management​

Every visual element in Caeros is a block, and csh gives you complete control over them (hold Ctrl+Shift to see block numbers):

# Create a new block showing a webpage
csh web open github.com

# Do a web search in a new block
csh web open "caeros terminal"

# Run a command in a new block and auto-close when done
csh run -x -- npm test

# Get information about the current block
csh getmeta

Common Workflows​

Here are some common ways to use csh:

Development Workflow​

# Open directory or markdown files
csh view .
csh view README.md

# add a -m to open the block in "magnified" mode
csh view -m README.md

# Start development server in a new block (-m will magnify the block on startup)
csh run -m -- npm run dev

# Open documentation in a web block
csh web open http://localhost:3000

Remote Development​

# Connect to remote server with optional key
csh ssh -i ~/.ssh/mykey.pem dev@server

# Edit remote files
csh edit /etc/nginx/nginx.conf

# Monitor remote logs
csh run -- tail -f /var/log/app.log

# Share variables between sessions
csh setvar -b tab SHARED_ENV=staging

AI-Assisted Development​

The csh ai command appends content to the Caeros AI sidebar. By default, files are attached without auto-submitting, allowing you to review and add more context before sending.

# Pipe output to AI sidebar (ask question in UI)
git diff | csh ai -

# Attach files with a message
csh ai main.go utils.go -m "find bugs in these files"

# Auto-submit with message
csh ai config.json -s -m "explain this config"

# Start new chat with attached files
csh ai -n *.log -m "analyze these logs"

# Attach multiple file types (images, PDFs, code)
csh ai screenshot.png report.pdf app.py -m "review these"

# Debug with stdin and auto-submit
dmesg | csh ai -s - -m "help me understand these errors"

Flags:

  • - - Read from stdin instead of a file
  • -m, --message - Add message text along with files
  • -s, --submit - Auto-submit immediately (default is to wait for user)
  • -n, --new - Clear chat and start fresh conversation

File Limits:

  • Text files: 200KB max
  • PDFs: 5MB max
  • Images: 7MB max
  • Maximum 15 files per command

Tips & Features​

  1. Working with Blocks

    • Use block numbers (1-9) to target specific blocks within a tab (hold Ctrl+Shift to see block numbers)
    • Can get full block ids by right click a block's header and selecting "Copy Block Id" (useful for scripting)
    • Use references like "this", "tab", "workspace", or "global" for different scopes

  2. Data Storage

    • Use csh setvar/getvar for configuration and secrets
    • Store file data using csh file, which can be easily referenced in all terminals (local and remote)
    • Use appropriate storage scopes (block, tab, workspace, global)

  3. Command Execution

    • Use csh run to execute commands in new blocks
    • Send command output and files quickly to AI blocks with csh ai

Scripting with csh​

csh commands can be combined in scripts to automate common tasks. Here's an example that sets up a development environment and uses csh notify to monitor a long-running build:

#!/bin/bash
# Setup development environment
csh run -- docker-compose up -d
csh web open localhost:8080
csh view ./src
csh run -- npm run test:watch

# Get notified when long-running tasks complete using csh notify
npm run build && csh notify "Build complete" || csh notify "Build failed"

Getting Help​

You can get help on available commands by running csh with no arguments, or get detailed help for a specific command using csh [command] -h.

For a complete reference of all csh functionality, see the CSH Command Reference.