### Heroku CLI Help Example

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

An example of Heroku CLI's help output for listing apps, demonstrating usage, options, and a brief description.

```Shell
<strong>$ heroku apps --help</strong>
list your apps

<strong>USAGE</strong>
  $ heroku apps

<strong>OPTIONS</strong>

```

--------------------------------

### Heroku Apps CLI Examples

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Demonstrates how to use the Heroku apps command with examples showing how to list personal and collaborated apps.

```bash
$ heroku apps
=== My Apps
example
example2

=== Collaborated Apps
theirapp   other@owner.name
```

--------------------------------

### jq Help Text Example

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Demonstrates the concise help text displayed by the `jq` command, including its purpose, usage, and a prompt for more detailed help.

```Shell
$ jq
jq - commandline JSON processor [version 1.6]

Usage:    jq [options] <jq filter> [file...]
    jq [options] --args <jq filter> [strings...]
    jq [options] --jsonargs <jq filter> [JSON_TEXTS...]

jq is a tool for processing JSON inputs, applying the given filter to
its JSON text inputs and producing the filter's results as JSON on
standard output.

The simplest filter is ., which copies jq's input to its output
unmodified (except for formatting, but note that IEEE754 is used
for number representation internally, with all that that implies).

For more advanced filters see the jq(1) manpage ("man jq")
and/or https://stedolan.github.io/jq

Example:

    $ echo '{"foo": 0}' | jq .
    {
        "foo": 0
    }

For a listing of options, use jq --help.

```

--------------------------------

### NPM LS Man Page Example

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

An example of a man page for the 'npm ls' command, detailing its name, synopsis, and description.

```APIDOC
NPM-LS(1)                                                            NPM-LS(1)

NAME
       npm-ls - List installed packages

SYNOPSIS
         npm ls [[<@scope>/]<pkg> ...]

         aliases: list, la, ll

DESCRIPTION
       This command will print to stdout all the versions of packages that are
       installed, as well as their dependencies, in a tree-structure.

       ...
```

--------------------------------

### Git Status Example

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Illustrates how a CLI can provide comprehensive information about the current system state and suggest next actions, similar to `git status`.

```Shell
git status
# On branch main
# Your branch is up to date with 'origin/main'.
#
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git restore <file>..." to discard changes in working directory)
# 	modified:   README.md
# 
# no changes added to commit (use "git add" and/or "git commit -a")
```

--------------------------------

### CLI Distribution Best Practices

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Recommendations for distributing CLI tools, prioritizing single binary distribution or using native package managers for easy installation and uninstallation.

```English
Distribute as a single binary if possible.
If not, use platform-native package installers.
Ensure easy uninstallation with clear instructions.
```

--------------------------------

### CLI Help Invocation Examples

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Illustrates various command-line invocations that should trigger help text display, including single flags, combined flags, and subcommand help.

```Shell
$ myapp
$ myapp --help
$ myapp -h
$ myapp help
$ myapp help subcommand
$ myapp subcommand --help
$ myapp subcommand -h

```

--------------------------------

### Example: Docker Compose Ctrl-C Handling

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Illustrates how a program might inform the user about graceful shutdown and the option to force stop upon receiving Ctrl-C.

```bash
$  docker-compose up
…
^CGracefully stopping... (press Ctrl+C again to force)
```

--------------------------------

### Example ls Output Formatting

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Demonstrates the typical output format of the `ls` command, showing file permissions, ownership, size, modification date, and name. This format allows users to quickly scan and understand file attributes.

```text
-rw-r--r-- 1 root root     68 Aug 22 23:20 resolv.conf
lrwxrwxrwx 1 root root     13 Mar 14 20:24 rmt -> /usr/sbin/rmt
drwxr-xr-x 4 root root   4.0K Jul 20 14:51 security
drwxr-xr-x 2 root root   4.0K Jul 20 14:53 selinux
-rw-r----- 1 root shadow  501 Jul 20 14:44 shadow
-rw-r--r-- 1 root root    116 Jul 20 14:43 shells
drwxr-xr-x 2 root root   4.0K Jul 20 14:57 skel
-rw-r--r-- 1 root root      0 Jul 20 14:43 subgid
-rw-r--r-- 1 root root      0 Jul 20 14:43 subuid
```

--------------------------------

### Commonly Used Flags

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

A list of standard and commonly used flags with their short and long forms, along with their typical meanings and examples of their usage in existing tools.

```APIDOC
-a, --all: All. For example, ps, fetchmail.
-d, --debug: Show debugging output.
-f, --force: Force. For example, rm -f will force the removal of files, even if it thinks it does not have permission to do it. This is also useful for commands which are doing something destructive that usually require user confirmation, but you want to force it to do that destructive action in a script.
--json: Display JSON output.
-h, --help: Help. This should only mean help.
-n, --dry-run: Dry run. Do not run the command, but describe the changes that would occur if the command were run. For example, rsync, git add.
--no-input: See the [interactivity](#interactivity) section.
-o, --output: Output file. For example, sort, gcc.
-p, --port: Port. For example, psql, ssh.
-q, --quiet: Quiet. Display less output. This is particularly useful when displaying output for humans that you might want to hide when running in a script.
-u, --user: User. For example, ps, ssh.
--version: Version.
-v: This can often mean either verbose or version. You might want to use -d for verbose and this for version, or for nothing to avoid confusion.
```

--------------------------------

### Yubikey-Agent Emoji and Symbol Usage Example

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Illustrates the use of emoji and symbols in CLI output for clarity and user attention, as demonstrated by the yubikey-agent tool. It shows how to convey information, warnings, and status updates effectively.

```shell
$ yubikey-agent -setup
🔐 The PIN is up to 8 numbers, letters, or symbols. Not just numbers!
❌ The key will be lost if the PIN and PUK are locked after 3 incorrect tries.

Choose a new PIN/PUK: 
Repeat the PIN/PUK: 

🧪 Retriculating splines …

✅ Done! This YubiKey is secured and ready to go.
🤏 When the YubiKey blinks, touch it to authorize the login.

🔑 Here's your new shiny SSH public key:
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCEJ/
UwlHnUFXgENO3ifPZd8zoSKMxESxxot4tMgvfXjmRp5G3BGrAnonncE7Aj11pn3SSYgEcrrn2sMyLGpVS0=

💭 Remember: everything breaks, have a backup plan for when this YubiKey does.
```

--------------------------------

### Environment Variable Naming Convention

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Environment variable names must adhere to specific rules for maximum portability. They should only contain uppercase letters, numbers, and underscores, and must not start with a number.

```guidelines
Valid names: O_O, OWO
Invalid names: my_var, 1st_var
```

--------------------------------

### Configuration Categories and Recommendations

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Categorizes configuration based on variability and scope, providing recommendations for how to supply each type.

```APIDOC
Category 1: Varies per invocation (e.g., debug level, dry run)
  Recommendation: Flags, potentially Environment Variables.

Category 2: Stable per invocation, varies between projects/users (e.g., non-default paths, color output, proxy settings)
  Recommendation: Flags and Environment Variables. Consider config files for complexity.

Category 3: Stable within a project, for all users (e.g., build configurations, Docker settings)
  Recommendation: Command-specific, version-controlled file.
```

--------------------------------

### Heroku CLI Documentation Philosophy

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Outlines the principles for creating effective Heroku CLI documentation, emphasizing clarity, accessibility, and different formats.

```bash
### Documentation {#documentation}

The purpose of [help text](#help) is to give a brief, immediate sense of what your tool is, what options are available, and how to perform the most common tasks. Documentation, on the other hand, is where you go into full detail. It’s where people go to understand what your tool is for, what it _isn’t_ for, how it works and how to do everything they might need to do.

**Provide web-based documentation.**
People need to be able to search online for your tool’s documentation, and to link other people to specific parts. The web is the most inclusive documentation format available.

**Provide terminal-based documentation.**
Documentation in the terminal has several nice properties: it’s fast to access, it stays in sync with the specific installed version of the tool, and it works without an internet connection.

**Consider providing man pages.**
[man pages](https://en.wikipedia.org/wiki/Man_page), Unix’s original system of documentation, are still in use today, and many users will reflexively check `man mycmd` as a first step when trying to learn about your tool. To make them easier to generate, you can use a tool like [ronn](http://rtomayko.github.io/ronn/ronn.1.html) (which can also generate your web docs).

However, not everyone knows about `man`, and it doesn’t run on all platforms, so you should also make sure your terminal docs are accessible via your tool itself. For example, `git` and `npm` make their man pages accessible via the `help` subcommand, so `npm help ls` is equivalent to `man npm-ls`.
```

--------------------------------

### CLI Analytics and User Data Handling

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Guidelines for collecting usage metrics and analytics for CLI tools, emphasizing user consent, transparency, and providing opt-in/opt-out mechanisms.

```English
Do not collect usage or crash data without explicit user consent (opt-in).
If using opt-out, be transparent about data collection on website or first run.
Clearly state what data is collected, why, its anonymity, anonymization process, and retention period.
Consider alternatives like instrumenting web docs, downloads, or direct user feedback.
```

--------------------------------

### Git Common Commands Help

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Shows how Git displays common commands and usage information in its top-level help text, prioritizing frequently used actions.

```Shell
$ git
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone      Clone a repository into a new directory
   init       Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add        Add file contents to the index
   mv         Move or rename a file, a directory, or a symlink
   reset      Reset current HEAD to the specified state
   rm         Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect     Use binary search to find the commit that introduced a bug
   grep       Print lines matching a pattern
   log        Show commit logs
   show       Show various types of objects
   status     Show the working tree status
...

```

--------------------------------

### Heroku Apps Subcommands

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Provides a list of available subcommands for managing Heroku apps, such as creating, destroying, and viewing app information.

```bash
  apps:create     creates a new app
  apps:destroy    permanently destroy an app
  apps:errors     view app errors
  apps:favorites  list favorited apps
  apps:info       show detailed app information
  apps:join       add yourself to a team app
  apps:leave      remove yourself from a team app
  apps:lock       prevent team members from joining an app
  apps:open       open the app in a web browser
  apps:rename     rename an app
  apps:stacks     show the list of available stacks
  apps:transfer   transfer applications to another user or team
  apps:unlock     unlock an app so any team member can join
```

--------------------------------

### CLI Naming Conventions

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Best practices for naming command-line programs, emphasizing simplicity, memorability, lowercase letters, and avoiding overly generic or short names.

```English
Use simple, memorable words.
Avoid generic names that conflict with existing commands.
Use only lowercase letters and dashes for separation.
Keep names short but not too short (reserve very short names for common utilities).
Make names easy to type.
```

--------------------------------

### CLI Argument Parsing Libraries

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Recommends using command-line argument parsing libraries to handle arguments, flags, help text, and spelling suggestions effectively. Lists popular libraries across various programming languages.

```English
Multi-platform: docopt (http://docopt.org)
Bash: argbash (https://argbash.dev)
Go: Cobra (https://github.com/spf13/cobra), cli (https://github.com/urfave/cli)
Haskell: optparse-applicative (https://hackage.haskell.org/package/optparse-applicative)
Java: picocli (https://picocli.info/)
Julia: ArgParse.jl (https://github.com/carlobaldassi/ArgParse.jl), Comonicon.jl (https://github.com/comonicon/Comonicon.jl)
Kotlin: clikt (https://ajalt.github.io/clikt/)
Node: oclif (https://oclif.io/)
Deno: parseArgs (https://jsr.io/@std/cli/doc/parse-args/~/parseArgs)
Perl: Getopt::Long (https://metacpan.org/pod/Getopt::Long)
PHP: console (https://github.com/symfony/console), CLImate (https://climate.thephpleague.com)
Python: Argparse (https://docs.python.org/3/library/argparse.html), Click (https://click.palletsprojects.com/), Typer (https://github.com/tiangolo/typer)
Ruby: TTY (https://ttytoolkit.org/)
Rust: clap (https://docs.rs/clap)
Swift: swift-argument-parser (https://github.com/apple/swift-argument-parser)
```

--------------------------------

### Heroku Apps CLI Options

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Lists the available command-line options for the Heroku apps command, including flags for filtering and output formatting.

```bash
  -A, --all          include apps in all teams
  -p, --personal     list apps in personal account when a default team is set
  -s, --space=space  filter by space
  -t, --team=team    team to use
  --json             output in json format
```

--------------------------------

### Recommended Less Pager Options

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Provides recommended command-line options for the `less` pager to enhance the user experience when viewing large amounts of text in a terminal. These options include ignoring case, enabling color, and preserving output.

```shell
less -FIRX
```

--------------------------------

### Using .env Files for Project-Specific Configuration

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Read environment variables from a local `.env` file when they are unlikely to change within a specific project directory. This allows for project-specific configurations without repeated manual input. Libraries exist in various languages to facilitate this.

```Rust
crates.io/crates/dotenv
```

```Node.js
npmjs.com/package/dotenv
```

```Ruby
github.com/bkeepers/dotenv
```

--------------------------------

### CLI Configuration Precedence

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Defines the order in which configuration parameters are applied, from highest to lowest precedence, for command-line tools.

```APIDOC
Configuration Precedence (Highest to Lowest):
1. Flags
2. Environment Variables (running shell)
3. Project-level Configuration (e.g., .env)
4. User-level Configuration
5. System-wide Configuration
```

--------------------------------

### Heroku CLI Command Suggestion Logic

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Explains the Heroku CLI's approach to handling incorrect commands, including suggesting alternatives and user interaction.

```bash
$ heroku pss
 ›   Warning: pss is not a heroku command.
Did you mean ps? [y/n]:
```

--------------------------------

### Success Output and State Changes

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

CLI commands should provide concise output on success and clearly indicate state changes. Suppressing output with flags like `-q` can be useful for scripting.

```Shell
# Example of a command that changes state and provides feedback
git push
# Output indicates objects enumerated, compressed, written, and remote status.

# Example of suppressing non-essential output
my_command -q
```

--------------------------------

### CLI Future-proofing: Avoiding Catch-all Subcommands

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Avoid creating catch-all subcommands that interpret unknown arguments as a default action. This prevents future subcommand additions from breaking existing scripts.

```guidelines
Don’t have a catch-all subcommand.
If you have a subcommand that’s likely to be the most-used one, you might be tempted to let people omit it entirely for brevity’s sake.
This has a serious drawback, though: now you can never add a subcommand named `echo`—or _anything at all_—without risking breaking existing usages.
```

--------------------------------

### CLI Future-proofing: Avoiding Time Bombs

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Design CLIs to remain functional over long periods, avoiding dependencies on external services that may cease to exist. Consider the long-term maintainability of your application.

```guidelines
Don’t create a “time bomb.”
Imagine it’s 20 years from now. Will your command still run the same as it does today, or will it stop working because some external dependency on the internet has changed or is no longer maintained?
```

--------------------------------

### CLI Output Formatting Options

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

CLIs should offer options to control output format, balancing human readability with machine parsability. Common flags include `--plain` for tabular data and `--json` for structured data.

```Shell
# Example usage with --plain for machine readability
my_command --plain | grep "specific_value"

# Example usage with --json for structured data
my_command --json > output.json
cat output.json | jq '.some_field'
```

--------------------------------

### CLI Future-proofing: Stable Subcommand Aliases

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Allow explicit and stable aliases for subcommands rather than relying on arbitrary abbreviations. This prevents conflicts when adding new commands.

```guidelines
Don’t allow arbitrary abbreviations of subcommands.
There’s nothing wrong with aliases—saving on typing is good—but they should be explicit and remain stable.
```

--------------------------------

### CLI Future-proofing: Additive Changes

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

When modifying CLI interfaces, prioritize additive changes over breaking ones. If a change is unavoidable, provide ample warning to users and offer a way to adapt their usage.

```guidelines
Keep changes additive where you can.
Rather than modify the behavior of a flag in a backwards-incompatible way, maybe you can add a new flag—as long as it doesn’t bloat the interface too much.
Warn before you make a non-additive change.
Before you do, forewarn your users in the program itself: when they pass the flag you’re looking to deprecate, tell them it’s going to change soon.
Make sure there’s a way they can modify their usage today to make it future-proof, and tell them how to do it.
```

--------------------------------

### Docker Image Pull Progress

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Demonstrates the typical output of a Docker image pull operation, showcasing progress bars for multiple layers being downloaded or extracted. This visual feedback helps users understand the status of long-running operations.

```Shell
$ docker image pull ruby
Using default tag: latest
latest: Pulling from library/ruby
6c33745f49b4: Pull complete 
ef072fc32a84: Extracting [================================================>  ]  7.569MB/7.812MB
c0afb8e68e0b: Download complete 
d599c07d28e6: Download complete 
f2ecc74db11a: Downloading [=======================>                           ]  89.11MB/192.3MB
3568445c8bf2: Download complete 
b0efebc74f25: Downloading [===========================================>       ]  19.88MB/22.88MB
9cb1ba6838a0: Download complete 

```

--------------------------------

### Signal Handling: Ctrl-C (INT Signal)

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

When a user sends an INT signal (Ctrl-C), the program should exit as soon as possible, providing immediate feedback before initiating any cleanup operations. Cleanup operations should have timeouts.

```guidelines
If a user hits Ctrl-C (the INT signal), exit as soon as possible.
Say something immediately, before you start clean-up.
Add a timeout to any clean-up code so it can’t hang forever.
```

--------------------------------

### Standard Environment Variables for CLI Behavior

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Leverage common environment variables to control CLI behavior such as color output, verbosity, editing files, network proxy settings, and terminal interactions.

```guidelines
NO_COLOR: Disable color output
FORCE_COLOR: Enable color output
DEBUG: Enable verbose output
EDITOR: Prompt user to edit files
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY: Network proxy settings
SHELL: Open interactive shell session
TERM, TERMINFO, TERMCAP: Terminal-specific escape sequences
TMPDIR: Create temporary files
HOME: Locate configuration files
PAGER: Automatically page output
LINES, COLUMNS: Screen size dependent output
```

--------------------------------

### Handling File Input/Output with '-'

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

CLIs should support using '-' to read from stdin or write to stdout, enabling seamless piping between commands without temporary files.

```bash
$ curl https://example.com/something.tar.gz | tar xvf -
```

--------------------------------

### User Escape and Interrupt Handling

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Ensure users can easily escape or interrupt the program, especially during network I/O or when wrapping other processes. Ctrl-C should always work, and clear instructions for escape sequences (like SSH's '~') should be provided.

```shell
# Ensure Ctrl-C is handled gracefully
trap "echo Exiting..."; exit INT
```

--------------------------------

### CLI Exit Code Convention

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Specifies that programs should return an exit code of zero on success and a non-zero value on failure. Non-zero exit codes should map to specific failure modes.

```English
Return zero exit code on success, non-zero on failure.
Map the non-zero exit codes to the most important failure modes.
```

--------------------------------

### Order-Independent Arguments and Flags

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Design CLIs so that arguments, flags, and subcommands are order-independent to improve user experience and predictability, especially when modifying commands.

```shell
mycmd --foo=1 subcmd
# works

$ mycmd subcmd --foo=1
# unknown flag: --foo
```

--------------------------------

### Secure Secret Handling via Files or Stdin

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Avoid reading secrets directly from flags (e.g., --password) due to security risks like exposure in `ps` output or shell history. Prefer using file flags (e.g., --password-file) or stdin.

```shell
# Insecure: --password flag
# Secure: --password-file flag or stdin
```

--------------------------------

### Optional Flag Values with 'none'

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

When a flag accepts an optional value, provide a special keyword like 'none' to explicitly indicate the absence of a value, avoiding ambiguity.

```shell
ssh -F none
```

--------------------------------

### Disabling Interactivity with --no-input

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Provide a `--no-input` flag to explicitly disable all prompts and interactive elements. If input is required, the command should fail with instructions on how to provide it via flags.

```shell
mycmd --no-input
```

--------------------------------

### CLI Output Streams

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Instructs that primary command output and machine-readable data should be sent to standard output (stdout). Log messages and errors should be sent to standard error (stderr) to avoid interfering with piped commands.

```English
Send output to stdout.
Send messaging to stderr.
```

--------------------------------

### Security Warning: Avoid Storing Secrets in Environment Variables

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Environment variables are prone to leakage and should not be used for storing sensitive information like credentials. Prefer secure alternatives such as credential files, pipes, AF_UNIX sockets, or secret management services.

```guidelines
Leakage vectors: Logs, process state (e.g., `curl -H "Authorization: Bearer $BEARER_TOKEN"`), `docker inspect`, `systemctl show`.
Secure alternatives: Credential files, pipes, AF_UNIX sockets, secret management services.
```

--------------------------------

### Signal Handling: Ctrl-C During Cleanup

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

If Ctrl-C is pressed during lengthy cleanup operations, skip the remaining cleanup and inform the user about the consequences, especially if it's a destructive action. The program should be robust enough to handle interrupted cleanup.

```guidelines
If a user hits Ctrl-C during clean-up operations that might take a long time, skip them.
Tell the user what will happen when they hit Ctrl-C again, in case it is a destructive action.
Your program should expect to be started in a situation where clean-up has not been run.
```

--------------------------------

### Disabling Color in CLI Applications

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Lists conditions under which color output should be disabled in CLI applications to ensure compatibility and user preference. This includes non-interactive terminals and specific environment variables.

```text
stdout or stderr is not an interactive terminal (a TTY).
The NO_COLOR environment variable is set and it is not empty.
The TERM environment variable has the value dumb.
The user passes the option --no-color.
MYAPP_NO_COLOR environment variable is set.
```

--------------------------------

### Conditional Interactivity (TTY Check)

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Prompts or interactive elements should only be used when stdin is connected to an interactive terminal (TTY). Otherwise, fail with an error instructing the user on how to provide input via flags.

```shell
# Check if stdin is a TTY before prompting
if [ -t 0 ]; then
  # Prompt user
else
  # Fail or use flag
fi
```

--------------------------------

### Secure Password Prompting (Echo Off)

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

When prompting for a password, disable terminal echo to prevent the characters from being displayed as the user types.

```shell
# Example using bash builtins (actual implementation depends on language/library)
read -s -p "Enter password: " password
echo
```

--------------------------------

### Detecting TTY in Programming Languages

Source: https://cli.github.io/cli-guidelines/cli-guidelines/refs/heads/main/content/_index

Detecting if a script is running in a TTY (teletypewriter) is crucial for determining whether to provide human-readable or machine-readable output. This is a common requirement across various programming languages.

```Python
import sys

if sys.stdout.isatty():
    print("Running in a TTY")
else:
    print("Not running in a TTY")
```

```Node.js
const isTTY = process.stdout.isTTY;

if (isTTY) {
  console.log('Running in a TTY');
} else {
  console.log('Not running in a TTY');
}
```

```Go
package main

import (
	"fmt"
	"github.com/mattn/go-isatty"
	"os"
)

func main() {
	isTerminal := isatty.IsTerminal(os.Stdout.Fd())

	if isTerminal {
		fmt.Println("Running in a TTY")
	} else {
		fmt.Println("Not running in a TTY")
	}
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.