BTCLSH(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

💅 BTCLSH(1) — the BRL-CAD manual, but make it make sense

okay so bestie, welcome to btclsh — this is the BRL-CAD Tcl shell and it's genuinely that girl ✨

🌸 NAME 🌸

btclsh — a Tcl shell with the BRL-CAD libraries already loaded in, no cap 🫶

✨ SYNOPSIS ✨

btclsh [script [arg ...]]

💖 DESCRIPTION 💖

So here's the vibe: btclsh is a Tcl interpreter with the BRL-CAD Tcl/Tk libraries preloaded, which means your Tcl scripts get direct access to BRL-CAD's geometry and database commands. it's giving "backstage pass." it's the non-graphical counterpart to bwish(1) — it needs no display server at all, which makes it the main character for text-based interactive work, scripting, and automation 🔥

Now, the rules of engagement:

  • if you hand it a script file and that name does not begin with a hyphen (-), btclsh evaluates that file and then exits. the leftover arg values get handed to your script through three Tcl variables: argv (the argument list), argc (the argument count), and argv0 (the script name). cute, organised, iconic 💅
  • with no script, or when the first argument begins with a hyphen, btclsh goes interactive and reads commands from standard input. that interactive session comes with command-line editing (Emacs-style key bindings, arrow-key history recall — yes bestie, you can press ↑) and it sources a startup file, ~/.btclshrc (~/.btclshrc.tcl on Windows), if one's there. a little pre-game ritual 🎀

On top of the full Tcl command set, btclsh registers a few built-in commands:

  • history [-delays] [-outfile file] — lists the command history. with -delays it also reports the elapsed time between commands; with -outfile it appends the listing to file instead of printing it. 🌈
  • hist add command | next | prev — maintains the command history: add a command, or step to the next or previous entry (this one's used internally by history recall, iykyk). 🦋
  • exit [status] / q [status] — leaves the shell, returning the optional integer status (defaults to 0). say bye bestie 👋
ngl, btclsh takes no command-line options at all, so it has no OPTIONS section. that's not me being lazy — that's literally the whole tea. 🍵

🧚 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

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

🌸 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. short, sweet, ate. 👑

🎀 SEE ALSO 🎀

💀 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 — don't be shy, they're literally asking 😭

and that's the whole page, bestie 💖 this iconic little manual page comes to you from BRL-CAD — go forth, script your geometry, and remember: no display server required. periodt. ✨🎀💅

📦 where this page comes from