Skip to content

installation.md

Latest commit

 

History

History
187 lines (127 loc) · 5.64 KB

installation.md

File metadata and controls

187 lines (127 loc) · 5.64 KB
Raw

Installation

This guide covers all supported ways to install tfctl and related documentation (man pages and TLDR pages).

Homebrew (macOS and Linux)

The simplest way to install on macOS/Linux with Homebrew:

brew tap tfctl/tfctl
brew install tfctl

Notes:

  • The Homebrew formula installs man pages. Try: man tfctl, man tfctl-sq.

Debian/Ubuntu (.deb package)

Download the .deb from the latest release and install:

# Example for amd64; adjust the filename for your architecture
curl -LO https://github.com/tfctl/tfctl/releases/latest/download/tfctl_amd64.deb \
  && sudo dpkg -i tfctl_amd64.deb || sudo apt-get -f install

Notes:

  • The Debian package installs man pages under /usr/share/man/man1.

Pre-built tarball (manual install)

Download the latest release for your platform from the releases page.

Extract and move the binary to your PATH:

tar xvzf tfctl_*.tar.gz
sudo mv tfctl /usr/local/bin

Install man pages (from tarball)

The tarball includes manual pages under docs/man/share/man1, but they aren’t auto-installed. If you’re unsure of your system’s man search paths, see the references at the end of this section.

Linux

  1. Find a suitable man directory (check your search path):
manpath
# or show where a page would be read from
man -w printf || true

Common choices are /usr/local/share/man (preferred for local installs) or /usr/share/man.

  1. Install the pages (adjust MANPREFIX if needed):
MANPREFIX=/usr/local/share/man
sudo install -d "$MANPREFIX/man1" "$MANPREFIX/man7"
sudo install -m 0644 docs/man/share/man1/* "$MANPREFIX/man1/"
sudo install -m 0644 docs/man/share/man7/* "$MANPREFIX/man7/"
# Update the whatis database (optional, man-db systems)
sudo mandb || true

macOS

  1. Check your man path and pick a prefix that exists in it:
manpath | tr ':' '\n'

On Intel macs, /usr/local/share/man is common; on Apple Silicon with Homebrew, /opt/homebrew/share/man is typical.

  1. Install the pages (adjust MANPREFIX if needed):
MANPREFIX=/usr/local/share/man   # or /opt/homebrew/share/man
sudo install -d "$MANPREFIX/man1" "$MANPREFIX/man7"
sudo install -m 0644 docs/man/share/man1/* "$MANPREFIX/man1/"
sudo install -m 0644 docs/man/share/man7/* "$MANPREFIX/man7/"
# Rebuild macOS whatis database (optional)
sudo /usr/libexec/makewhatis "$MANPREFIX" || true

Windows

  • Native Windows doesn’t ship a man viewer. If you use WSL, follow the Linux steps inside your distro. If you use MSYS2/Cygwin/Git Bash, use the shell’s own manpath and copy into that environment’s /usr/share/man or /usr/local/share/man.

Verify installation

man -w tfctl     # shows the file path if the page is found
man tfctl        # opens the main tfctl page
man tfctl-sq     # opens the sq subcommand page

Helpful references (how man finds pages)

Install TLDR pages (from tarball)

Tip: Most tfctl query commands support --tldr to show a short usage page, for example: tfctl oq --tldr. This requires a TLDR client to be installed and the tfctl pages to be available to that client (either via upstream pages or local pages configured as below).

The tarball also includes TLDR pages under docs/tldr. These are compatible with common TLDR clients (e.g., tldr, tlrc), but clients don’t auto-load third-party pages by default. You have two options:

  • Contribute these pages upstream to the community repo so they’re fetched like any other page; or
  • Point your TLDR client to a local pages directory or mirror that includes docs/tldr.

Below are general approaches for popular clients. Consult your client’s docs for the most accurate, up-to-date details.

Prerequisite: install a TLDR client

  • Linux/macOS (Node.js client): npm install -g tldr
  • Linux/macOS (Rust client): brew install tlrc (macOS/Homebrew) or cargo install tlrc (Rust toolchain)

Linux

  1. Choose a pages folder. For many clients, a reasonable local path is:
TLDRPAGES="$HOME/.local/share/tldr/pages"
mkdir -p "$TLDRPAGES"
cp -a docs/tldr/* "$TLDRPAGES/"
  1. Point your client at that folder:
  • For tlrc, set a config file (example ~/.config/tlrc/config.toml):
[directories]
pages = ["$HOME/.local/share/tldr/pages"]
  • For the Node.js tldr client, you can set TLDR_CACHE_DIR to a directory containing pages/ (client behavior may vary by version):
export TLDR_CACHE_DIR="$HOME/.cache/tldr"
mkdir -p "$TLDR_CACHE_DIR/pages"
cp -a docs/tldr/* "$TLDR_CACHE_DIR/pages/"

Then try:

tldr tfctl
tldr tfctl sq

macOS

The steps are the same as Linux; adjust any paths for Homebrew conventions. For example, with tlrc installed via Homebrew, configure ~/.config/tlrc/config.toml as above.

Windows

  • WSL: follow the Linux steps inside your distro.
  • MSYS2/Cygwin/Git Bash: use the shell’s HOME and XDG paths (e.g., ~/.local/share/tldr/pages), then configure your client similarly.

Helpful references (tldr clients)

Build from source

git clone https://github.com/tfctl/tfctl.git
cd tfctl && go build -o tfctl

Build with GoReleaser

goreleaser build --snapshot --clean --single-target