termancy

termancy reads configuration from TOML, YAML, JSON, ZON, and dotenv files, layers it with environment variables and overrides, and lets you query, explain, edit, and convert it (termancy cfg). termancy cli and termancy tui generate new applications and components; termancy ui gives shell scripts interactive widgets. The other commands read Markdown, show images, record terminals, sign releases, manage SSH keys and passkeys, and update termancy.

Usage:
  termancy <command>

termancy cfg

Read configuration from TOML, YAML, JSON (with or without comments), ZON, dotenv, and INI files, layered with environment variables and --set overrides. Without --config, the first termancy.toml, termancy.yaml, termancy.yml, termancy.json, termancy.zon, termancy.env, termancy.jsonc, or termancy.ini found in ., $XDG_CONFIG_HOME/termancy, or ~/.config/termancy is loaded.

Usage:
  termancy cfg <command>

Aliases: config

termancy cfg get

Print the effective value of a key. Scalars print bare; tables and arrays print in the --output format (YAML for text).

Usage:
  termancy cfg get [flags] <key>

Examples

termancy cfg get server.port --default 8080
termancy cfg get servers.0.host -c prod.toml
termancy cfg get server -o json

termancy cfg keys

List every key that has a value

Usage:
  termancy cfg keys [flags] [prefix]

termancy cfg show

Print the whole effective configuration

Usage:
  termancy cfg show [flags]

Examples

termancy cfg show -c base.toml -c local.yaml -o toml
termancy cfg show --secret db.password
termancy cfg show --layer env --env-prefix APP

termancy cfg explain

For every key, or the keys under a prefix, print the effective value and the layer that supplied it: default, file, profile, env, flag, or override (--set). Secrets (from encrypted files, ${secret:...}, or --secret) are redacted unless --reveal.

Usage:
  termancy cfg explain [flags] [prefix]

termancy cfg env

Print one command per key that sets an environment variable to the effective value, named the way --env-prefix reads it: server.port with --prefix APP is APP_SERVER_PORT. Arrays of scalars join with commas; null values and empty tables are left out. Values are single-quoted, so evaluating the output runs nothing in them. Fails, printing nothing, when two keys map to the same name or a name would not be a valid variable name.

Usage:
  termancy cfg env [flags]

Examples

eval "$(termancy cfg env --prefix APP)"
termancy cfg env --prefix APP --shell fish | source
termancy cfg env --shell powershell | Out-String | Invoke-Expression

termancy cfg profile

A profile is a profiles.<name> section, applied over the rest of the file. --profile (or $TERMANCY_PROFILE) chooses one for a run; "profile use" records one in the config file, as current_profile, for every run that does not choose.

Usage:
  termancy cfg profile <command>

termancy cfg profile list

List the profiles; * marks the one in use

Usage:
  termancy cfg profile list [flags]

termancy cfg profile use

Use a profile by default

Usage:
  termancy cfg profile use [flags] <name>

Examples

termancy cfg profile use staging
termancy cfg profile use --clear

termancy cfg set

Set a key in the file named by the first --config, or the discovered termancy.* file. The value's type is inferred: true/false, integers, and decimals are typed, null is null, a TOML date or time (2024-01-01, 07:32:00) is a date-time, anything else is a string. --string keeps it a string. A missing file is created.

Usage:
  termancy cfg set [flags] <key> <value>

Examples

termancy cfg set server.port 9090 -c app.toml
termancy cfg set version 1.10 --string -c app.yaml

termancy cfg unset

Remove a key from the config file

Usage:
  termancy cfg unset [flags] <key>

Aliases: rm

termancy cfg edit

Open a copy of [file] (default: the first --config, or the discovered termancy.* file) in $VISUAL or $EDITOR. When the editor exits, the copy must parse: if it does, it replaces the file at once; if not, the error is shown and you choose to edit again or give up, leaving the file as it was, as visudo does. Needs a terminal.

Usage:
  termancy cfg edit [flags] [file]

termancy cfg convert

Convert a file to another format

Usage:
  termancy cfg convert [flags] <file|->

Examples

termancy cfg convert app.toml --to yaml
cat app.json | termancy cfg convert - --from json --to toml

termancy cfg validate

Parse each file and report the first error in each, with its line and column. With --schema, also check each file against a JSON Schema and report every place it does not conform, as "<file>: <key>: <problem>". Text where the schema wants a number or a boolean is accepted when it reads as one, as dotenv and INI hold only text. Exits with status 1 if any file is invalid. With no files, check the effective configuration instead, as every other command reads it: the files --config names (or the termancy.* file found), with the profile, the environment (--env-prefix), and --set applied. Every problem is reported, at the file and line that set the key, or naming the variable or flag that did. Nothing is written. A file is also checked (with a warning, not a failure; -q silences it) for what parses but is likely a mistake: a value that looks like a secret written in plain text (a key such as password or token, not a ${secret:...} reference), a key the schema marks deprecated, and a key the schema does not declare but that is close to one it does (as prot is to port).

Usage:
  termancy cfg validate [flags] [<file>...]

Examples

termancy cfg validate app.toml prod.yaml --schema schema.json
termancy cfg validate --schema schema.json -c app.toml --profile prod --set port=0

termancy cfg fmt

Rewrite each file in canonical form: consistent indentation, quoting, and spacing. TOML, ZON, and dotenv files keep their comments and key order; other formats are written as termancy writes them, and lose their comments (with a warning). With --check, list the files that would change and exit with status 1 if there are any. --sort sorts keys and tables by name. In TOML, keys are sorted within each group (lines a blank line sets apart stay apart), and a key or a table takes the comments directly above it along; other formats lose their comments.

Usage:
  termancy cfg fmt [flags] <file>...

termancy cfg redact

Print <file> with the value of every key that looks secret replaced by "<redacted>", keeping its keys, comments, and layout: for a bug report. A key looks secret when its name holds password, passwd, secret, token, api_key, apikey, or private_key, the names "termancy cfg validate" warns about; everything under such a table is secret too. --secret names more keys. Empty values and ${...} references give nothing away and are kept. The file itself is not changed. Where a value cannot be replaced in place (an item of a JSON array, say), the whole file is written as termancy writes it, losing its comments, with a warning.

Usage:
  termancy cfg redact [flags] <file|->

Examples

termancy cfg redact app.toml > app-redacted.toml
termancy cfg redact app.yaml --secret db.url
cat .env | termancy cfg redact - --from env

termancy cfg diff

Print the keys whose values differ between <old> and <new>, which may be in different formats. A key only in <old> prints as "- key = value", one only in <new> as "+ key = value", and a changed key as both lines. Exits with status 0 when the files hold the same configuration and 1 when they differ, as diff(1) does. -o json prints one object per key, sorted by key: [{"key": string, "change": "added" | "removed" | "changed", "old": any, "new": any}] "old" is null for an added key and "new" for a removed one. With --layer twice and no files, compare two layers of the loaded configuration instead: --layer file --layer env shows what the environment overrides.

Usage:
  termancy cfg diff [flags] <old> <new>

Examples

termancy cfg diff base.toml prod.yaml
termancy cfg diff old.json new.json -o json
termancy cfg diff --layer file --layer env --env-prefix APP

termancy cfg encrypt

Write <file>.enc: the file encrypted with XChaCha20-Poly1305 under a key derived from the passphrase (Argon2id). The passphrase comes from $TERMANCY_PASSPHRASE, or is asked for at a terminal. Every termancy command reads the .enc file with -c when $TERMANCY_PASSPHRASE is set, treating all of its values as secret.

Usage:
  termancy cfg encrypt [flags] <file>

Examples

TERMANCY_PASSPHRASE=... termancy cfg encrypt secrets.toml
termancy cfg -c secrets.toml.enc get db.password

termancy cfg decrypt

Print what <file> (made by "termancy cfg encrypt") holds. The passphrase comes from $TERMANCY_PASSPHRASE, or is asked for at a terminal.

Usage:
  termancy cfg decrypt [flags] <file>

Examples

termancy cfg decrypt secrets.toml.enc > secrets.toml

termancy cfg merge

Merge the files in order, later files winning, tables merging key by key, and print the result in the --output format (YAML for text). The files may be in different formats; profiles, the environment, and --set do not apply.

Usage:
  termancy cfg merge [flags] <file>...

Examples

termancy cfg merge base.toml prod.yaml -o toml > merged.toml

termancy cfg init

Write [file] (default: termancy.toml), in the format its extension names: a short example, or with --schema, every property the schema declares, set to its default (or to an empty value of its type). Refuses to replace a file unless --force.

Usage:
  termancy cfg init [flags] [file]

Examples

termancy cfg init
termancy cfg init app.yaml --schema schema.json

termancy cfg schema

Infer a JSON Schema, or check files against one

Usage:
  termancy cfg schema <command>

termancy cfg schema infer

Print a JSON Schema (draft-07) describing <file>: its keys and their types, every key required. A starting point to edit: loosen what may vary, add bounds and enums, then check files with "termancy cfg schema check".

Usage:
  termancy cfg schema infer [flags] <file>

Examples

termancy cfg schema infer termancy.toml > schema.json

termancy cfg schema check

The same as "termancy cfg validate --schema <schema> <file>...".

Usage:
  termancy cfg schema check [flags] <schema> <file>...

termancy cli

Generate cli applications; documentation and completion for termancy

Usage:
  termancy cli <command>

termancy cli init

Write build.zig, build.zig.zon, src/main.zig, an example command in src/cmd/hello.zig, README.md, and .gitignore for a new application called <name>. The termancy dependency is a path with --module-path, or is fetched with --fetch (which runs zig fetch --save=termancy <url>); with neither, add it yourself before building. Refuses to write into a non-empty directory without --force.

Usage:
  termancy cli init [flags] <name>

Examples

termancy cli init demo --module-path ../termancy
termancy cli init demo --fetch git+https://github.com/93ams/termancy

termancy cli add

Write a command with a typed flags struct, a handler that prints what it receives, and a test, then list it in its parent. Every word of the path but the last is a group, created when missing. Flag types: bool, count, int, uint, i8...i64, u8...u64, float, f32, f64, string, enum(a|b|c), list(T). A scalar without a default is optional (?T) unless marked required.

Usage:
  termancy cli add [flags] <command>...

Examples

termancy cli add greet --flag name:string=world --summary "Greet someone"
termancy cli add config get --flag key:string,required --flag verbose:count,short=v
termancy cli add files copy --args 2: --flag mode:enum(fast|safe)=safe
termancy cli add deploy --flow --flag env:enum(staging|production) --flag version:string,required

termancy cli docs

Print the documentation of the whole command tree to standard output: Markdown, one man page, one HTML page, or JSON (see docs/machine-output.md). With --dir and --format man, write one page per command instead (termancy.1, termancy-cfg.1, termancy-cfg-get.1, ...), linked to each other under SEE ALSO.

Usage:
  termancy cli docs [flags]

Examples

termancy cli docs > TERMANCY.md
termancy cli docs --format man > termancy.1
termancy cli docs --format man --dir man/man1
termancy cli docs --format html > termancy.html
termancy cli docs --format html --stylesheet site.css > commands.html

termancy cli repl

Read command lines and run each as termancy would, without the leading "termancy": "cfg get server.port", then "cfg keys", and so on. Words are split as a shell splits them, without expansions. "exit", "quit", or the end of input ends the shell, with the status of the last line run. Standard input may be a script: printf 'cfg keys\ncfg get name\n' | termancy cli repl.

Usage:
  termancy cli repl [flags]

Examples

termancy cli repl
termancy cli repl < commands.txt

termancy cli completion

Print a script that makes the shell complete this program's commands, flags, and flag values. Each shell's subcommand says how to load it; "install" puts it where the shell loads it by itself.

Usage:
  termancy cli completion <command>

termancy cli completion bash

Print the bash completion script. Load it with: source <(<this command>) The first lines of the script name the exact command.

Usage:
  termancy cli completion bash [flags]

termancy cli completion zsh

Print the zsh completion script. Load it with: source <(<this command>) The first lines of the script name the exact command.

Usage:
  termancy cli completion zsh [flags]

termancy cli completion fish

Print the fish completion script. Load it with: <this command> | source The first lines of the script name the exact command.

Usage:
  termancy cli completion fish [flags]

termancy cli completion powershell

Print the powershell completion script. Load it with: <this command> | Out-String | Invoke-Expression The first lines of the script name the exact command.

Usage:
  termancy cli completion powershell [flags]

termancy cli completion install

Write the completion script where the shell loads it by itself: bash $XDG_DATA_HOME/bash-completion/completions/<app> (with bash-completion) zsh ~/.zfunc/_<app> (~/.zfunc must be in fpath, before compinit) fish $XDG_CONFIG_HOME/fish/completions/<app>.fish Without a shell, uses the one $SHELL names. PowerShell has no such place; the command says what to add to $PROFILE instead. Run it again after an update.

Usage:
  termancy cli completion install [flags] [shell]

termancy tui

Components to copy into your project

Usage:
  termancy tui <command>

termancy tui init

Write tui.zon in the project directory (-C) and create the component directory. tui.zon records where components go and the SHA-256 of every file termancy tui add writes: .{ .dir = "src/ui", .components = .{} } Components import the tui module of termancy. When build.zig does not import it yet, init prints the line to add; for a build.zig made by termancy cli init, --wire adds it. For any other project, --dependency <url> adds termancy to build.zig.zon with zig fetch (a local path works too) and, for a build.zig shaped like zig init's, adds the dependency and the import before b.installArtifact(exe). Run again on an initialized project, init changes only what is missing. The build.zig is the nearest one in the project directory or a parent of it, so a subdirectory of a monorepo works too.

Usage:
  termancy tui init [flags]

Examples

termancy tui init
termancy tui init --dir src/components -C demo --wire
termancy tui init --dependency git+https://github.com/93ams/termancy

termancy tui add

Copy each component, and every component it requires, into the directory tui.zon names, and record each file's SHA-256 in tui.zon. One line per file: created the file was missing updated the file was as termancy tui add last wrote it, and the registry has changed unchanged the file is already the registry's version skipped (modified; use --force) the file was edited; termancy tui diff <component> shows how retired (no longer part of <component>; use --prune) a file an earlier version had; --prune removes it removed with --prune, a retired file as termancy tui add wrote it kept (retired, modified) with --prune, a retired file that was edited, left alone Exits 1 when a file was skipped. --force replaces edited files too. With no components named, at a terminal, choose them from a list: space chooses, enter adds, esc cancels. Elsewhere, name at least one.

Usage:
  termancy tui add [flags] <component>...

Examples

termancy tui add
termancy tui add select
termancy tui add form tabs --dry-run
termancy tui add select --force -C demo

termancy tui list

List every component in the registry with its summary and, when the project has a tui.zon, its state: - (not installed), installed, modified (a file was edited or removed), outdated (the registry has a newer version), or modified,outdated. -o json prints one object, keys in this order: {"version": 1, "manifest": bool, "components": [{"name": string, "summary": string, "requires": [string], "files": [string], "installed": bool, "modified": bool, "outdated": bool}]} "manifest" says whether tui.zon was found; without it, every component is not installed. "version" changes only when the shape does.

Usage:
  termancy tui list [flags]

Examples

termancy tui list
termancy tui list -o json -C demo

termancy tui diff

Print a unified diff from each file of the component in the project (--- side) to the registry's version (+++ side); a missing file compares as empty. As with diff(1), exits 0 when they are identical, 1 when they differ, and 2 when the component is unknown or not installed.

Usage:
  termancy tui diff [flags] <component>

Examples

termancy tui diff select
termancy tui diff select -C demo | less

termancy ui

Terminal widgets for shell scripts, and demos of the components

Usage:
  termancy ui <command>

termancy ui choose

Show the items (the arguments, or the lines of standard input) and print the one chosen. With --limit above 1 or --no-limit, space chooses each item and enter prints them all, one per line, in their original order. Keys: up/down or j/k move, pgup/pgdown and home/end jump, enter chooses, esc cancels (status 1), Ctrl-C interrupts (status 130). The list is drawn on the terminal even when standard output is not one.

Usage:
  termancy ui choose [flags] [item...]

Examples

termancy ui choose red green blue
git branch --format='%(refname:short)' | termancy ui choose --header "Branch?"
termancy ui choose --limit 2 a b c d

termancy ui confirm

Ask the question (default "Are you sure?") and exit with status 0 for yes and 1 for no. Nothing is printed. Keys: left/right or tab switch buttons, enter answers, y and n answer directly, esc cancels (status 1), Ctrl-C interrupts (status 130).

Usage:
  termancy ui confirm [flags] [prompt]

Examples

termancy ui confirm "Deploy to production?" && ./deploy
termancy ui confirm --default no --affirmative Delete --negative Keep

termancy ui input

Read one line and print it. Keys: the usual line editing (left/right, home/end, backspace, ctrl+w, ctrl+u, ctrl+k), enter submits, esc cancels (status 1), Ctrl-C interrupts (status 130).

Usage:
  termancy ui input [flags]

Examples

name=$(termancy ui input --placeholder "Your name")
token=$(termancy ui input --password --header "API token")

termancy ui write

Read text of any number of lines and print it. Enter starts a new line; Ctrl-D submits; esc cancels (status 1); Ctrl-C interrupts (status 130).

Usage:
  termancy ui write [flags]

Examples

git commit -m "$(termancy ui write --header "Commit message")"

termancy ui filter

Show the items (the lines of standard input, or the arguments) and narrow them as you type: an item matches when it contains the query's characters in order, best matches first, matched characters highlighted. Case is ignored unless the query has an uppercase letter. Prints the chosen item; with --limit above 1 or --no-limit, tab chooses each and enter prints them all, one per line, in their original order. Keys: typing edits the query, up/down (ctrl+p/ctrl+n) move, enter chooses, esc cancels (status 1), Ctrl-C interrupts (status 130).

Usage:
  termancy ui filter [flags] [item...]

Examples

vim "$(find . -type f | termancy ui filter)"
git log --oneline | termancy ui filter --no-limit | cut -d' ' -f1

termancy ui spin

Run the command after -- and show a spinner on the terminal until it ends. Then print what the command wrote to standard output (and standard error, to standard error), and exit with its status. With --show-output, the command writes directly as it runs instead. Without a terminal, the command runs the same way with no spinner. Ctrl-C stops the command and exits with status 130, printing nothing. A command that cannot be found exits with status 127.

Usage:
  termancy ui spin [flags] -- <command> [arg...]

Examples

termancy ui spin --title "Building..." -- zig build
files=$(termancy ui spin -- find / -name '*.zig')

termancy ui table

Read CSV (or, with --separator, any one-character-separated values) from standard input: the first line holds the column titles unless --columns gives them. Fields may be quoted ("a, b"), with "" for a quote inside. Interactively, up/down move, enter prints the chosen row as a line of the same format, esc cancels (status 1), and Ctrl-C interrupts (status 130). With --print, the table is written to standard output instead, colored only where standard output shows colors.

Usage:
  termancy ui table [flags]

Examples

termancy ui table < people.csv
ps -eo pid,comm | tr -s ' ' | sed 's/^ //' | termancy ui table -s ' ' | cut -d' ' -f1
termancy ui table --print --separator tab < data.tsv

termancy ui pager

Show a file (or standard input) full screen, lines wrapped to the terminal's width. Keys: j/k or up/down scroll a line, space/b or pgdown/pgup a screen, d/u half a screen, g/G or home/end jump to either end; / searches (ignoring case), n and N go to the next and previous match. v opens the file in $VISUAL or $EDITOR and shows it again when the editor exits. q quits; esc quits with status 1; Ctrl-C with 130.

Usage:
  termancy ui pager [flags] [file]

Examples

termancy ui pager README.md
termancy cfg show | termancy ui pager

termancy ui file

Browse from [dir] (default: the current directory) and print the absolute path of the file chosen. Directories come first. Keys: up/down or j/k move; enter, right, or l open a directory or choose a file; left, h, or backspace go up; . shows or hides dotfiles. esc or q cancels (status 1), Ctrl-C interrupts (status 130).

Usage:
  termancy ui file [flags] [dir]

Examples

$EDITOR "$(termancy ui file --ext .md)"
termancy ui file --all ~/.config

termancy ui style

Print the arguments (one per line), or standard input, laid out as a block in the given style. Colors and attributes are written only when standard output shows them: not into a pipe or a file, and not under NO_COLOR (FORCE_COLOR overrides). Borders, padding, and alignment are always applied.

Usage:
  termancy ui style [flags] [text...]

Examples

termancy ui style --border rounded --padding "0 2" --foreground 212 "Hello"
echo done | termancy ui style --bold --foreground green

termancy ui format

Format the arguments (one per line), or standard input. As Markdown (the default): headings, emphasis, lists, quotes, tables, task lists, links, and highlighted code blocks, wrapped to the width. As code: highlighted for --language. As emoji: :shortcodes: replaced. As a template: {{ Bold "x" }}, {{ Italic "x" }}, {{ Faint "x" }}, {{ Underline "x" }}, {{ CrossOut "x" }}, {{ Color "fg" "bg" "x" }}, {{ Foreground "fg" "x" }}, {{ Background "bg" "x" }}, and pipes: {{ "x" | Bold | Color "212" "" }}. Colors are written only where standard output shows them (as for termancy ui style).

Usage:
  termancy ui format [flags] [text...]

Examples

termancy ui format "# Done" "Everything **passed**."
termancy ui format < CHANGELOG.md
termancy ui format -t code -l zig < build.zig
termancy ui format -t emoji ":rocket: shipped"
termancy ui format -t template '{{ Bold "Hello" }} {{ "world" | Color "212" "" }}'

termancy ui join

Join the arguments, each a block of lines, side by side (or one above another with --vertical), padding each to line up. Escape sequences take no room, so blocks from termancy ui style join cleanly.

Usage:
  termancy ui join [flags] <text>...

Examples

termancy ui join "$(termancy ui style --border rounded A)" "$(termancy ui style --border rounded B)"
termancy ui join --vertical --align center "Title" "a longer line"

termancy ui log

Write the message (the first argument) and fields (the arguments after it, as key value pairs) as one log record on standard error, styled as charm's log at a terminal, or as logfmt or JSON lines. Values whose keys look secret (password, token, ...) are redacted.

Usage:
  termancy ui log [flags] <message> [key value]...

Examples

termancy ui log --level warn "disk almost full" used 93%
termancy ui log -f json --time rfc3339 "deployed" version 1.4.0

termancy ui demo

Run a component of the registry on sample data, as it would run in your project after termancy tui add. Without a name, list the components that have a demo. q or esc ends a demo of a component that does not end by itself.

Usage:
  termancy ui demo [flags] [component]

Examples

termancy ui demo
termancy ui demo tree
termancy ui demo chart --svg > chart.svg

termancy md

Render Markdown, as glow does. The source is a file, - for standard input, an http(s) URL, a repository (github.com/owner/repo or gitlab.com/owner/repo, for its README), or a directory (the current one by default), whose Markdown files are listed to choose from. At a terminal the document opens in a reader: j/k and the arrows scroll, g/G go to the ends, e edits the file in $EDITOR, r reloads it, c copies the source to the clipboard, esc goes back to the list, q quits. Elsewhere (or with --print) it is printed, without colors where they would not show.

Usage:
  termancy md [flags] [source]

Examples

termancy md README.md
termancy md github.com/ziglang/zig
termancy md -s light -w 70 CHANGELOG.md
curl -s https://example.com/notes.md | termancy md -
termancy md docs/

termancy image

Draw an image (PNG, JPEG, or a GIF's first frame; - for standard input) at the cursor. The way is the terminal's best: the kitty graphics protocol (kitty, Ghostty), iTerm2's inline images (iTerm2, WezTerm, VS Code), sixels (foot, mlterm, Windows Terminal), or else half blocks, two pixels a cell, in as many colors as show. When the environment does not say, auto asks the terminal (kitty's graphics query and the device attributes), waiting at most 200 ms.

Usage:
  termancy image [flags] <file>

Examples

termancy image logo.png
termancy image photo.jpg
termancy image -w 40 -p mosaic demo.gif

termancy freeze

Draw a file (or standard input) as highlighted code, or the output of a command (-x, run on a pseudo-terminal so its colors show), into a PNG, in a window with an optional bar, rounded corners, a border and a drop shadow; or into an SVG. The font is the machine's: --font-family names one, else a common monospace font.

Usage:
  termancy freeze [flags] [file]

Examples

termancy freeze main.zig --window --shadow -o main.png
termancy freeze main.zig -n --lines 10,30 -t dracula
termancy freeze -x "ls --color=always" -o ls.svg
cat query.sql | termancy freeze -l sql

termancy record

Run a tape (a script of commands: Type "text", Enter, Sleep 2s, Wait /regex/, ...) in a shell on a pseudo-terminal and record what the terminal shows. Tapes written for vhs run as they are. Outputs (Output lines, or -o): .gif, .png (the last frame), a directory/ of PNG frames, .txt or .ascii (each screen as text, for golden tests), .svg (animated, sharp at any size), and .mp4 or .webm (needs ffmpeg). Fonts are the machine's: Set FontFamily names one, else a common monospace font is found.

Usage:
  termancy record [flags] <file.tape>
  termancy record <command>

Examples

termancy record new demo
termancy record demo.tape
termancy record demo.tape -o demo.svg -o golden.txt
termancy record validate demo.tape

termancy record new

Write a new tape to start from

Usage:
  termancy record new [flags] <name>

termancy record validate

Check tapes for errors without running them

Usage:
  termancy record validate [flags] <file.tape>...

termancy record capture

Start a shell in this terminal and note everything typed in it; when the shell exits, write it as a tape (Type, the keys, Sleep for pauses) to record later. Refuses a file that already exists, as new does.

Usage:
  termancy record capture [flags] <file.tape>

termancy record themes

List the color themes

Usage:
  termancy record themes [flags]

termancy explain

Show what each control character and escape sequence in terminal output does, one per line: colors and attributes, cursor movement, erasing, modes, titles, hyperlinks, queries, and the text between them. The output comes from the files given, from standard input, or from a command after `--`, which runs on a pseudo-terminal of --width by --height, so it draws as it does for a person; its questions to the terminal (colors, cursor position, modes) are answered.

Usage:
  termancy explain [flags] [file...] [-- command...]

Examples

printf '\033[1;31mred\033[0m\n' | termancy explain
termancy explain -- ls --color=always
termancy explain --no-text -- termancy ui choose a b

termancy serve

Listen for SSH connections and run the command after -- for each one, on a pseudo- terminal the size of the client's, following its resizes. Logins are by public key: the keys in --authorized-keys (by default your own ~/.ssh/authorized_keys), or, with --anyone, no login at all. The command sees TERM, SSH_USER, SSH_CLIENT_KEY (the key's fingerprint) and SSH_ORIGINAL_COMMAND (what the client asked to run, never run itself). The host key is made on first use and kept. With --web, browsers connect instead: open the link it prints, whose token (new each run) lets you in; --anyone drops the token. Each tab runs its own command, with TERM=xterm-256color and COLORTERM=truecolor. There is no TLS: off this machine, put it behind a reverse proxy that adds it.

Usage:
  termancy serve [flags] -- command...

Examples

termancy serve -- termancy ui demo
termancy serve --anyone -l 0.0.0.0:2222 -- htop
ssh -p 2222 localhost
termancy serve --web -- htop

termancy ssh

SSH: run commands remotely; keys: make, show, back up as words, sign, verify

Usage:
  termancy ssh <command>

termancy ssh run

Connect to the host, check its key against known_hosts, log in (with -i's key, then the Ed25519 keys of the ssh-agent at $SSH_AUTH_SOCK, or on Windows of OpenSSH's agent when it is not set, then ~/.ssh/id_ed25519; or as anyone, when the server allows it), run the command after --, and show its output; termancy ends with the command's exit status (255 when it has none). Standard input is not sent (as ssh -n). A host not in known_hosts is refused unless --accept-new, which records it; a changed key is always refused.

Usage:
  termancy ssh run [flags] [user@]host -- command...

Examples

termancy ssh run alice@example.com -- uname -a
termancy ssh run -p 2222 -i deploy_key --accept-new localhost -- uptime

termancy ssh keygen

Make an Ed25519 key pair, as ssh-keygen -t ed25519

Usage:
  termancy ssh keygen [flags]

Examples

termancy ssh keygen -f ~/.ssh/id_ed25519
TERMANCY_PASSPHRASE=... termancy ssh keygen -f deploy_key -C deploy

termancy ssh fingerprint

Show the fingerprints of public or private keys

Usage:
  termancy ssh fingerprint [flags] <key>...

termancy ssh melt

Print the key's seed (the whole private key) as 24 BIP 39 words, as Charm's melt does. Anyone with the words has the key: keep them as you would the key. Restore the key with `termancy ssh restore`.

Usage:
  termancy ssh melt [flags] <private key>

termancy ssh restore

Remake a private key from its 24 words (read from standard input)

Usage:
  termancy ssh restore [flags]

Examples

termancy ssh restore -f id_ed25519 < words.txt

termancy ssh sign

Sign files, as ssh-keygen -Y sign (writes <file>.sig)

Usage:
  termancy ssh sign [flags] <file>...

termancy ssh verify

Check that <file>.sig (or --signature) signs the file in the namespace, and print the signer's fingerprint. With --signers, the signer must also be one of the keys in that file; without it, any valid signature passes, so check the fingerprint printed.

Usage:
  termancy ssh verify [flags] <file>

termancy passkey

A WebAuthn client: get and create read the options a relying party sends (the JSON form of navigator.credentials.get() and create(), from the file or standard input), ask the authenticator, and print the response's JSON form. On Windows, Windows Hello asks; on Linux, get asks the first FIDO security key under /dev/hidraw, with its PIN when the relying party requires user verification. create needs Windows Hello.

Usage:
  termancy passkey <command>

termancy passkey get

Sign a challenge with a credential (navigator.credentials.get)

Usage:
  termancy passkey get [flags] [options.json]

Examples

curl -s https://example.com/login/options | termancy passkey get --origin https://example.com

termancy passkey create

Create a credential (navigator.credentials.create)

Usage:
  termancy passkey create [flags] [options.json]

Examples

termancy passkey create --origin https://example.com options.json > response.json

termancy release

Tools for publishing releases that sys.update installs: an Ed25519 signing key, a signature beside each asset (<asset>.sig, base64), and Homebrew, Scoop, and Arch Linux manifests generated from the release's SHA256SUMS.

Usage:
  termancy release <command>

termancy release keygen

Write a new Ed25519 secret key to <file>, readable only by its owner, and print the public key, base64, for the program that verifies updates (update.Options.public_key). Refuses to replace a file that exists. Keep the secret key out of the repository; in CI, pass its contents in $TERMANCY_SIGNING_KEY.

Usage:
  termancy release keygen [flags] <file>

Examples

termancy release keygen release.key

termancy release sign

Sign each <file> with the Ed25519 secret key and write the signature, base64, to <file>.sig, which sys.update downloads and checks when a public key is set.

Usage:
  termancy release sign [flags] <file>...

Examples

termancy release sign --key release.key termancy-linux-x86_64.tar.gz
TERMANCY_SIGNING_KEY=... termancy release sign *.tar.gz *.zip

termancy release verify

Check each <file> against <file>.sig with the public key, as sys.update does before it installs. Exit status 1 when any signature is missing or does not verify.

Usage:
  termancy release verify [flags] <file>...

Examples

termancy release verify --public-key MCowBQ... termancy-linux-x86_64.tar.gz

termancy release manifest

Print a Homebrew formula, Scoop or winget manifest, or Arch PKGBUILD for the assets listed in --sums. An asset's OS and CPU come from its name (termancy-linux-x86_64.tar.gz, termancy-windows-aarch64.zip); its download is --url joined with the name. An archive is taken to hold the executable at its top level, named --name (with .exe on Windows).

Usage:
  termancy release manifest [flags]

Examples

termancy release manifest -f homebrew --version 0.3.0 \
    --url https://github.com/93ams/termancy/releases/download/v0.3.0 > termancy.rb

termancy dirs

Print the config, cache, data, state, and runtime directories of [app] (default: termancy): XDG on Linux and the BSDs, ~/Library on macOS, known folders on Windows. Nothing is created. A directory the system does not define prints as - (null in JSON); today that is only runtime, without $XDG_RUNTIME_DIR. With --search, print the directories a configuration loader should search, most specific first, one per line. -o json prints one object, keys in this order: {"app": string, "os": string, "config": string, "cache": string, "data": string, "state": string, "runtime": string or null} or, with --search: {"app": string, "os": string, "search": [string, ...]}

Usage:
  termancy dirs [flags] [app]

Examples

termancy dirs
termancy dirs myapp -o json
termancy dirs --search

termancy info

Print what termancy knows about the system it runs on: OS and architecture (as compiled), the Zig and termancy versions, the CI service (from its environment variables), whether standard input and output are terminals, whether the process runs elevated (root or an administrator), and the host name. -o json prints one object, keys in this order: {"os": string, "arch": string, "zig": string, "termancy": string, "ci": string or null, "stdin_tty": bool, "stdout_tty": bool, "elevated": bool, "hostname": string or null} "ci" is one of github_actions, gitlab, buildkite, circleci, travis, jenkins, azure_pipelines, teamcity, bitbucket, appveyor, drone, codebuild, or generic.

Usage:
  termancy info [flags]

Examples

termancy info
termancy info -o json

termancy update

Look up the latest release of 93ams/termancy on GitHub and, when it is newer than this termancy, download the archive for this OS and architecture (.tar.gz; .zip on Windows), check it against the release's SHA-256 checksum and Ed25519 signature, unpack termancy from it, and replace the running executable (keeping a rollback copy until the new one has run `--version`). Pre-releases and drafts are ignored. Without --yes, asks for confirmation on the terminal; without one (or under CI) it refuses instead, before any network access, so a script never waits on a prompt. -v logs the URLs, the archive chosen, and the checks made.

Usage:
  termancy update [flags]

Examples

termancy update --check
termancy update --yes

termancy version

Print version information

Usage:
  termancy version [flags]

Exit status