CLI Reference

Keecas provides a comprehensive command-line interface for configuration management and Jupyter integration.

Installation and Verification

Check Version

keecas --version

Shows the installed Keecas version and verifies the CLI is working.

Help

keecas --help

Display all available commands and options.

Configuration Management

Initialize Configuration

Create new configuration files with default settings:

# Create global configuration (~/.keecas/config.toml)
keecas config init --global

# Create local configuration (.keecas/config.toml)
keecas config init --local

# Force overwrite existing configuration
keecas config init --global --force
keecas config init --local --force

Edit Configuration

Open configuration files for editing:

# Edit with terminal editor ($EDITOR)
keecas config edit --global
keecas config edit --local

# Open with system default editor (GUI)
keecas config open --global
keecas config open --local

Note: edit uses your terminal editor (vim, nano, etc.) while open uses your system’s default application (VS Code, gedit, etc.).

View Configuration

Display current configuration settings:

# Show merged configuration (local + global + defaults)
keecas config show

# Show only global configuration
keecas config show --global

# Show only local configuration
keecas config show --local

# Show configuration file paths
keecas config path

Reset Configuration

Reset configuration files to defaults:

# Reset global configuration
keecas config reset --global

# Reset local configuration
keecas config reset --local

# Force reset without confirmation
keecas config reset --global --force

Check Configuration Version

Display configuration file version information:

# Check local configuration version (default)
keecas config version

# Check global configuration version
keecas config version --global

Shows the schema version, creation date, and modification date of the configuration file.

Migrate Configuration

Migrate configuration files to the latest schema version:

# Migrate local configuration (default)
keecas config migrate

# Migrate global configuration
keecas config migrate --global

# Preview migration without applying changes
keecas config migrate --dry-run
keecas config migrate --global --dry-run

Used when upgrading Keecas to ensure configuration files are compatible with the new version.

Jupyter Integration

Development Environment

Launch Jupyter with Keecas templates and optimized settings:

# Basic launch
keecas edit

# Open specific file
keecas edit my_calculation.ipynb

# Launch with template
keecas edit --template basic
keecas edit --template structural-analysis
keecas edit --template beam-design

# Custom settings
keecas edit --port 8889 --no-browser --token mytoken
keecas edit --dir /path/to/project --no-lab

Options:

  • --template TEMPLATE: Use predefined notebook template
  • --port PORT: Jupyter server port (default: 8888)
  • --dir DIR: Working directory for Jupyter
  • --no-browser: Don’t open browser automatically
  • --token TOKEN: Set Jupyter access token
  • --no-lab: Use Jupyter Notebook instead of JupyterLab
  • --temp: Create temporary notebook (not saved)
  • --sandbox: Run in an isolated uv environment with the notebook’s inline dependencies (requires uv)
  • --no-sandbox: Never offer sandbox mode

Sandboxed Notebooks (Inline Dependencies)

A notebook can declare the packages it needs with a PEP 723 block in a code cell. The cell holds only comments, so running it is a no-op:

# /// script
# requires-python = ">=3.12"
# dependencies = ["scipy", "pandas>=2"]
# ///

keecas edit --sandbox reads the block and relaunches itself through uv run in an isolated, ephemeral environment containing keecas plus those dependencies. The Jupyter server and kernel both run there, so the notebook can import them:

uvx keecas edit analysis.ipynb --sandbox
  • Without --sandbox, opening a notebook that declares dependencies asks whether to use a sandbox (interactive terminals only, and only if uv is installed). --no-sandbox skips the question.
  • keecas is added at the running version (keecas==X.Y.Z) unless the block lists keecas itself.
  • uv is not a keecas dependency: --sandbox exits with an install hint when uv is missing.
  • Only one block per notebook; a second one is an error.
  • In the sandbox, the python3 kernel always runs on the sandbox’s Python, and other registered kernels (ipykernel install --user, conda environments, …) are hidden, so a notebook cannot silently run in an environment without its declared dependencies.

List Available Templates

# Show all available templates
keecas edit --list-templates

Templates include: - basic: Simple calculation setup - structural-analysis: Engineering analysis template - beam-design: Structural beam calculations - verification: Safety verification template

Claude Code Skill Integration

keecas bundles two Claude Code skills:

  • keecas-notebook - core conventions for keecas calculation notebooks: symbols, the _p/_e/_v/_d/_l dicts, the pc.subs | pc.convert_to | pc.N values pipeline, show_eqn, descriptions and verifications. Applies to any Jupyter notebook.
  • keecas-quarto - the Quarto layer on top of it: init cells, %run of shared notebooks, cell options, fitting rows to the page, tables and figures for a PDF calculation report.

Each skill tells Claude to load the other when both apply.

Install the Skills

keecas skill install

# Overwrite existing installations
keecas skill install --force

This installs into ~/.claude/skills/keecas-notebook/ and ~/.claude/skills/keecas-quarto/. Skills already installed are left alone unless --force is given, so running it again after upgrading keecas adds any newly bundled skill. Where the platform supports it, each skill is symlinked to the version bundled with your installed keecas package, so it updates automatically on pip install -U keecas; otherwise (e.g. Windows without symlink support) it falls back to a plain copy, and you should re-run keecas skill install --force after upgrading keecas. A stale install from a previous keecas version’s legacy location is removed automatically. Restart Claude Code (or open a new session) after installing.

Use the Skills with Other AI Tools

For AI tools that don’t understand Claude Code’s Skill format (OpenAI Codex CLI, Cursor, Copilot, or a plain chat session), print the skill content to stdout instead of installing it, and paste or redirect it wherever you need:

# Print the core keecas-notebook guidance
keecas skill print

# Add the keecas-quarto guidance (for notebooks rendered by Quarto)
keecas skill print --quarto

# Include the skills' reference docs too (several times the size)
keecas skill print --quarto --with-references

# e.g. append it to a project-level AGENTS.md
keecas skill print --quarto --with-references >> AGENTS.md

Output is always UTF-8, regardless of the console encoding. This makes no filesystem writes on its own – it’s plain text on stdout, so it works the same on every OS and with any tool that accepts pasted or piped context.

Configuration File Format

Configuration files use TOML format with hierarchical settings:

Global Configuration (~/.keecas/config.toml)

# Global defaults for all projects

[language]
language = "en"
disable_pint_locale = true

[display]
katex = false
pint_default_format = ".3f~P"
default_float_format = ".3f"

[latex]
eq_prefix = "eq-"

[custom_translations]
"VERIFIED" = "VERIFIED"
"Domain" = "Domain"

Local Configuration (.keecas/config.toml)

# Project-specific overrides

[language]
language = "it"                    # Italian for this project

[display]
katex = true                       # VS Code compatibility

[latex]
eq_prefix = "eq-bridge-analysis-"  # Project-specific prefix

[custom_translations]
"VERIFIED" = "VERIFICATO"          # Italian verification terms

Priority Order

  1. Local (.keecas/config.toml)
  2. Global (~/.keecas/config.toml)
  3. Defaults (built-in)

Cross-Platform Support

The CLI works consistently across platforms:

Linux

# Uses $EDITOR for terminal editing
# Uses xdg-open for GUI editing
keecas config edit --global
keecas config open --global

macOS

# Uses $EDITOR for terminal editing
# Uses open for GUI editing
keecas config edit --global
keecas config open --global

Windows

# Uses %EDITOR% for terminal editing
# Uses start for GUI editing
keecas config edit --global
keecas config open --global

Error Handling

Common CLI issues and solutions:

Configuration Not Found

$ keecas config show --global
Error: Global configuration not found

# Solution: Initialize configuration
$ keecas config init --global

Editor Not Set

$ keecas config edit --global
Error: No editor configured

# Solution: Set environment variable
$ export EDITOR=nano
$ keecas config edit --global

Invalid TOML Syntax

$ keecas config show
Error: Invalid TOML syntax in config file

# Solution: Reset or manually fix configuration
$ keecas config reset --global --force

Permission Issues

$ keecas config init --global
Error: Permission denied

# Solution: Check home directory permissions
$ ls -la ~/.keecas/
$ chmod 755 ~/.keecas/

Automation and Scripting

Batch Configuration

#!/bin/bash
# Setup script for new projects

# Initialize local config
keecas config init --local

# Set project-specific settings
cat > .keecas/config.toml << EOF
[language]
language = "en"

[display]
katex = true

[latex]
eq_prefix = "eq-${PROJECT_NAME}-"
EOF

echo "Keecas configured for ${PROJECT_NAME}"

CI/CD Integration

# GitHub Actions example
- name: Setup Keecas
  run: |
    pip install keecas
    keecas config init --global
    keecas config show  # Verify configuration

Jupyter Notebook Automation

# Create and launch template notebook
keecas edit calculation.ipynb --template structural-analysis --no-browser

# Convert notebook to other formats (requires nbconvert)
jupyter nbconvert calculation.ipynb --to pdf

Development Workflow

Typical Project Setup

# 1. Create project directory
mkdir my-analysis && cd my-analysis

# 2. Initialize local configuration
keecas config init --local

# 3. Customize for project
keecas config edit --local

# 4. Launch development environment
keecas edit analysis.ipynb --template basic

Multi-Project Management

# Each project can have its own settings
cd project-a/
keecas config init --local
# Configure for Italian engineering standards

cd ../project-b/
keecas config init --local
# Configure for German engineering standards

# Global settings remain consistent
keecas config show --global

Troubleshooting Commands

Diagnostic Information

# Check installation
keecas --version

# Verify configuration files exist and are readable
keecas config path
ls -la $(keecas config path --global)
ls -la $(keecas config path --local)

# Test configuration parsing
keecas config show --global
keecas config show --local
keecas config show  # merged

# Check Jupyter integration
keecas edit --help

Reset Everything

# Nuclear option: reset all configuration
keecas config reset --global --force
keecas config reset --local --force

# Reinitialize with defaults
keecas config init --global
keecas config init --local

Integration with Other Tools

VS Code Integration

# Launch with VS Code optimized settings
keecas config init --local
echo -e '\n[display]\nkatex = true' >> .keecas/config.toml
keecas edit notebook.ipynb

Quarto Integration

# Configure for Quarto document generation
keecas config init --local
cat > .keecas/config.toml << EOF
[language]
language = "en"

[display]
katex = false

[latex]
eq_prefix = "eq-doc-"
EOF

Docker Integration

# Dockerfile for Keecas environment
FROM python:3.12
RUN pip install keecas
RUN keecas config init --global
COPY config.toml /root/.keecas/config.toml

Next Steps