Configuration

tg resolves configuration values from the following sources, in increasing precedence (later sources override earlier ones):

1. Defaults. appview is https://bobbin.klbr.net. knot is unset to permit automatic verified Knot discovery. ssh-port is 22. protocol is ssh.
2. Config file — $XDG_CONFIG_HOME/tg/config.toml (or ~/.config/tg/config.toml)
3. Environment variables — prefixed TG_ (e.g. TG_APPVIEW)
4. Command-line flags — e.g. --appview

The config file is optional; a missing file is not an error.

Config file

~/.config/tg/config.toml

appview = "https://bobbin.klbr.net"
knot = "knot.example.com"
ssh-port = 2222
protocol = "ssh"

knot selects where tg repo create provisions a repository. If you select a Knot explicitly, new repository DID remotes connect to that Knot. ssh-port sets the port for direct SSH clone and push remotes. Automatically selected Knots use the tangled.org proxy on SSH port 22.

protocol selects the URL used by tg repo clone and tg repo create --clone. Set it to ssh (the default) or https. If the repository record contains a repository DID, tg uses the DID in the remote. An explicitly selected Knot uses a direct remote. HTTPS clones that fall back to handle/repo use the repository’s recorded Knot.

Override the config file location with --config /path/to/config.toml.

Environment variables

Variable	Config key	Purpose
TG_APPVIEW	appview	Appview host URL
TG_ACCOUNT	account	Account handle or DID
TG_KNOT	knot	Knot host for repo creation
TG_SSH_PORT	ssh-port	SSH port for an explicitly selected Knot
TG_PROTOCOL	protocol	Clone URL protocol (ssh or https)

Keys containing . or - map to TG_-prefixed underscore-separated names (e.g. foo.bar → TG_FOO_BAR).

Flags

Flag	Purpose
--config	Path to config file
--appview	Appview host URL (overrides config file and TG_APPVIEW)
--account	Account handle or DID for this command

Automatic verified Knot discovery

When you don’t specify a Knot with --knot, repo creation reads up to 10 Knot registrations from your PDS and verifies each registration. Select a Knot explicitly if you have more than 10 registrations. Exactly one verified Knot is selected automatically. If no registrations exist, it falls back to knot1.tangled.sh. One registration that can’t be verified errors. If tg successfully verifies multiple Knots, it errors and lists the candidates so you can specify one with --knot or set it in the config file.

Set knot in your config, TG_KNOT in your environment, or pass --knot to select a host explicitly and bypass automatic discovery. The flag overrides the environment, which overrides the config file.

Shell completions

Put the relevant tg completion command in your shell config to source the completions on startup or pipe the generated completions to a file somewhere your shell will source on startup.

Bash

This goes in your config and increases shell startup latency because of command invocation overhead, but doesn’t require updating later

source <(tg completion bash)

Run these to generate completions that’ll later need updating. They depend on bash-completion.

mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions"
# run to generate, rerun to update
tg completion bash > "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/tg.bash"

Zsh

This goes in your config and increases shell startup latency because of command invocation overhead, but doesn’t require updating later. Put it somewhere after loading your Zsh framework or compinit.

source <(tg completion zsh)

Run these to generate completions that’ll later need updating

mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions"
# run to generate, rerun to update
tg completion zsh > "${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions/_tg"

Sourcing the generated completions automatically requires this somewhere in your config before loading your Zsh framework or compinit.

fpath=("${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions" $fpath)

Fish

This goes in your config and increases shell startup latency because of command invocation overhead, but doesn’t require updating later

tg completion fish | source

Run these to generate completions that’ll later need updating

mkdir -p "$__fish_config_dir/completions"
# run to generate, rerun to update
tg completion fish > "$__fish_config_dir/completions/tg.fish"

PowerShell

This goes in your PowerShell profile and increases shell startup latency because of command invocation overhead, but doesn’t require updating later

tg completion powershell | Out-String | Invoke-Expression

Run these to generate completions that’ll later need updating

New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE) | Out-Null
# run to generate, rerun to update
tg completion powershell | Set-Content -Encoding utf8 -Path (Join-Path (Split-Path -Parent $PROFILE) "tg-completion.ps1")

Then add this to your PowerShell profile:

. (Join-Path (Split-Path -Parent $PROFILE) "tg-completion.ps1")