Skip to documentation
BRL-CAD
DocumentationAll documentsEnglish

BTCLSH(1)

NAME

btclsh - Tcl shell with BRL-CAD libraries loaded

On this page

SYNOPSIS

btclsh [script [arg ...]]

DESCRIPTION

btclsh is a Tcl interpreter with the BRL-CAD Tcl/Tk libraries preloaded, giving Tcl scripts direct access to BRL-CAD’s geometry and database commands. It is the non-graphical counterpart to bwish(1): it requires no display server and is suited to text-based interactive work, scripting, and automation.

If a script file is given and its name does not begin with a hyphen (-), btclsh evaluates that file and exits. Any remaining arg values are made available to the script through the Tcl variables argv (the argument list), argc (the argument count), and argv0 (the script name).

With no script, or when the first argument begins with a hyphen, btclsh runs interactively, reading commands from standard input. The interactive session offers command-line editing (Emacs-style key bindings, arrow-key history recall) and sources a startup file, ~/.btclshrc (~/.btclshrc.tcl on Windows), if present.

Besides the full Tcl command set, btclsh registers a few built-in commands:

history [-delays] [-outfile file]

List the command history. With -delays, also report the elapsed time between commands; with -outfile, append the listing to file instead of printing it.

hist add command | next | prev

Maintain the command history: add a command, or step to the next or previous entry (used internally by history recall).

exit [status] / q [status]

Leave the shell, returning the optional integer status (default 0).

Because btclsh takes no command-line options, it has no OPTIONS section.

EXAMPLES

Example 1. Scripting a geometry query with arguments
cat > volume.tcl <<'EOF'
opendb [lindex $argv 0] y
puts [bb -v [lindex $argv 1]]
EOF

btclsh volume.tcl moss.g all.g

Runs a Tcl script that opens the geometry database moss.g (passed as the first argument) and prints the bounding-box and volume report for the all.g object using the libged bb command. This shows how btclsh drives BRL-CAD database commands non-interactively, with arguments forwarded through the Tcl argv variable.

Example 2. Interactive session
btclsh
btclsh> opendb moss.g y
btclsh> ls
btclsh> q

Starts the interactive shell, opens a database, lists its objects with the libged ls command, then quits.

SEE ALSO

brlcad(1), bwish(1), mged(1)

AUTHOR

BRL-CAD Team

This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org