CLI Reference

Complete reference for CalcMark CLI commands, flags, and shell completion.

Overview #

The CalcMark CLI (cm) provides commands for editing, evaluating, converting, and exploring CalcMark documents.

cm [file]            # Open editor (default command)
cm eval [file.cm]    # Evaluate and print results
cm convert <file.cm> # Convert to another format
cm remote            # Open a remote document
cm config            # Print or create configuration
cm help              # Show available topics and flags
cm help functions    # List all CalcMark functions
cm help constants    # List all unit constants
cm help frontmatter  # List all frontmatter directives
cm help --all        # Show everything at once
cm version           # Print version info
cm completion [shell] # Generate shell completions

Global Flags #

The --color-mode flag is available on all commands. Use light or dark to match your terminal background. The value auto is accepted but deprecated and treated as dark.

The --locale flag controls decimal and thousands separators in output. See Configuration: Display Locale for details.

cm [file] #

Open the CalcMark editor. With no arguments, starts with an empty document. With a file argument, opens that file for editing.

When stdin is piped, cm automatically evaluates the input and prints results to stdout instead of launching the editor. This makes CalcMark usable in shell pipelines and by AI agents.

Flags (piped mode) #

Examples #

cm                              # New document (interactive editor)
cm budget.cm                    # Edit existing file
cm --color-mode=dark            # Force dark mode

echo "x = 42" | cm             # Evaluate piped input (text output)
echo "x = 42" | cm --format json  # JSON output for scripting/agents
echo "x = 10" | cm -v          # Verbose output with all values
cat budget.cm | cm --format json   # Pipe a file through cm

See Editor Shortcuts in the User Guide for keyboard shortcuts.

cm eval [file.cm] #

Evaluate a CalcMark file or stdin and print results.

Flags #

Examples #

cm eval budget.cm                    # Print final results
cm eval -v budget.cm                 # Show all intermediate values
echo "x = 10" | cm eval             # Evaluate from stdin
echo "5 miles in km" | cm eval
cm eval --locale=de-DE budget.cm     # German number formatting
cm eval --format json budget.cm      # JSON output with type decomposition
cm eval --format html doc.cm         # HTML document
cm eval --format md budget.cm        # Markdown with embedded results

When reading from a file, only the last evaluated result is printed unless -v is used. With -v, every line that produces a value is shown.

Use --format to select the output format. The available formats are the same as cm convert --to (see Output Formats). The default format can be changed in Configuration via default_format.

Use --locale to format output with locale-specific separators (e.g., 1.500,00 instead of 1,500.00 for de-DE).

cm convert <file.cm> #

Convert a CalcMark file to another format. Requires the --to flag.

Flags #

Examples #

cm convert doc.cm --to=html              # HTML to stdout
cm convert doc.cm --to=md -o doc.md      # Markdown to file
cm convert doc.cm --to=json              # JSON to stdout
cm convert doc.cm --to=text              # Plain text
cm convert doc.cm --to=html -T tpl.html  # Custom HTML template
cm convert --show-template               # Print default HTML template
cm convert doc.cm --to=json --locale=de-DE  # JSON with German formatting

Output Formats #

Note: The cm format is always locale-independent to ensure portability. All other formats respect the --locale flag.

Custom HTML Templates #

CalcMark uses Go’s html/template package for HTML output. You can provide your own template to control the HTML structure and styling.

Get the default template as a starting point:

cm convert --show-template > my-template.html

Use your custom template:

cm convert doc.cm --to=html -T my-template.html

Template Data Model #

The template receives a root object with two fields:

Block fields (each item in .Blocks):

SourceLine fields (each item in .SourceLines):

JSON output: In JSON format, each result includes value (locale-formatted for display), type (CalcMark type name), numeric_value (machine-readable number), and unit (unit identifier). Use type for dispatch, numeric_value + unit for computation. See Configuration: JSON Output and Locale.

Frontmatter fields (when .Frontmatter is non-nil):

Each global has .Name and .Value. Each exchange rate has .From, .To, and .Rate.

Minimal Custom Template #

<!DOCTYPE html>
<html>
<body>
  {{range .Blocks}}
    {{if eq .Type "calculation"}}
      <pre>
      {{range .SourceLines}}
        {{.Source}}{{if .Result}} = {{.Result}}{{end}}
      {{end}}
      </pre>
    {{else}}
      <div>{{.HTML}}</div>
    {{end}}
  {{end}}
</body>
</html>

cm remote #

Fetch a CalcMark document from a remote source and open it in the editor.

Flags #

Exactly one of --gist or --http must be provided.

Examples #

cm remote --gist abc123def                           # Open by gist ID
cm remote --gist https://gist.github.com/user/abc123 # Open by gist URL
cm remote --http https://example.com/budget.cm        # Open from any public URL

Gist Mode (--gist) #

The --gist flag accepts any identifier that gh gist view supports: a gist ID, a full gist URL, or a URL to any user’s public gist. For multi-file gists, the first .cm file is opened (or the first file if no .cm file exists).

Requires the GitHub CLI (gh) to be installed and authenticated (gh auth login).

HTTP Mode (--http) #

The --http flag fetches content from a public URL via HTTP GET. Only http:// and https:// URLs are accepted.

Safety limits:

• Maximum response size: 1 MB
• Binary content is rejected
• Empty responses are rejected
• Redirect targets must stay on HTTP(S)
• Connection timeout: 30 seconds

cm config #

Print the current effective configuration or create a starter config file.

Flags #

Examples #

cm config                    # Print effective configuration as TOML
cm config > backup.toml      # Save current config to a file
cm config --create           # Create ~/.config/calcmark/config.toml
cm config --check            # Validate all config files

Without flags, cm config prints the fully-resolved effective configuration (embedded defaults merged with user overrides and CLI flag overrides) as valid TOML to stdout.

With --create, a starter config file is written to ~/.config/calcmark/config.toml (or $XDG_CONFIG_HOME/calcmark/config.toml if set) with all values commented out and descriptive comments included. The command refuses to overwrite an existing file.

With --check, all config files are validated for TOML syntax, valid hex colors (#RGB or #RRGGBB), valid color_mode values (light, dark, auto), valid default_format values, and unknown keys. File discovery results and any errors are printed to stderr. Exits with code 0 if everything is valid, or code 1 if any errors were found.

cm help #

Browse CalcMark’s built-in reference — functions, unit constants, and frontmatter directives.

Topics are also available as flags:

cm help                  # Show available topics
cm help functions        # Functions only
cm help constants        # Unit constants only
cm help frontmatter      # Frontmatter directives only
cm help --functions      # Same as cm help functions
cm help --all            # Everything at once
cm help eval             # Help for a specific command

cm version #

Print the CalcMark version and build time.

cm version
# CalcMark v1.5.0
#   built: 2026-03-06T19:40:55Z

The version and build time reflect the installed release. Development builds show CalcMark dev.

cm completion [shell] #

Generate shell completion scripts. Supports bash, zsh, fish, and powershell.

Setup #

Bash:

source <(cm completion bash)
# Or persist in ~/.bashrc:
cm completion bash >> ~/.bashrc

Zsh:

cm completion zsh > "${fpath[1]}/_cm"
# Then restart shell or run: compinit

Fish:

cm completion fish > ~/.config/fish/completions/cm.fish

PowerShell:

cm completion powershell | Out-String | Invoke-Expression