bcs.1

.\" BCS Manual Page
.\" Generated: 2026-04-17
.\"
.TH BCS 1 "April 2026" "BCS 2.0.1" "User Commands"
.\"
.SH NAME
bcs \- Bash Coding Standard CLI toolkit
.\"
.SH SYNOPSIS
.B bcs
.RI [ display ]
.RI [ OPTIONS ]
.br
.B bcs template
.RI [ OPTIONS ]
.br
.B bcs check
.RI [ OPTIONS ]
.I SCRIPT
.br
.B bcs codes
.br
.B bcs generate
.RI [ OPTIONS ]
.br
.B bcs help
.RI [ COMMAND ]
.\"
.SH DESCRIPTION
.B bcs
is a CLI toolkit for working with the Bash Coding Standard (BCS), a set of
98 concise, actionable rules (plus 12 section overviews) across 12 sections
for Bash 5.2+ scripts. Designed by Okusi Associates for the Indonesian Open
Technology Foundation (YaTTI), the standard targets both human programmers
and AI assistants.
.PP
The toolkit provides six subcommands for viewing, generating templates,
checking compliance, listing rule codes, and regenerating the standard
document from section source files.
.\"
.SH COMMANDS
.SS bcs display
View the Bash Coding Standard document. This is the default command when
no subcommand is specified.
.PP
When stdout is a terminal and
.B md2ansi
is available, the standard is displayed with ANSI formatting piped through
.BR less (1).
Otherwise, plain text output is used.
.TP
.BR \-c ", " \-\-cat
Plain text output (no formatting).
.TP
.BR \-f ", " \-\-file
Show full path to the standard document.
.TP
.BR \-S ", " \-\-symlink
Symlink BASH-CODING-STANDARD.md into the current directory.
.TP
.BR \-h ", " \-\-help
Show display help and exit.
.\"
.SS bcs template
Generate BCS-compliant script templates with placeholder substitution.
.TP
.BR \-t ", " \-\-type " " \fITYPE\fR
Template type:
.BR minimal " (~16 lines),"
.BR basic " (~26 lines, default),"
.BR complete " (~119 lines),"
.BR library " (~40 lines)."
.TP
.BR \-n ", " \-\-name " " \fINAME\fR
Script name for placeholders.
.TP
.BR \-d ", " \-\-desc " " \fITEXT\fR
Script description.
.TP
.BR \-V ", " \-\-version " " \fIVER\fR
Version string (default: 1.0.0).
.TP
.BR \-o ", " \-\-output " " \fIFILE\fR
Output file (default: stdout).
.TP
.BR \-x ", " \-\-executable
Make output file executable.
.TP
.BR \-f ", " \-\-force
Overwrite existing files.
.TP
.BR \-h ", " \-\-help
Show template help and exit.
.\"
.SS bcs check
AI-powered BCS compliance checking. Analyzes a script against the full
standard and reports violations, warnings, and suggestions with BCS rule
codes. Supports multiple LLM backends: local Ollama, Anthropic API, OpenAI
API, Google Gemini API, and Claude Code CLI. The backend is selected
entirely from the
.B \-m
model name \(em there is no separate backend flag.
.TP
.BR \-m ", " \-\-model " " \fIMODEL\fR
Quality tier or concrete model ID. Tier keywords
.BR fast ","
.BR balanced " (default), and"
.BR thorough
probe available backends in order (ollama, anthropic, openai, google, claude)
and use the first reachable one with that tier's default model. Any other
value is passed through to the backend sniffed from the name:
.BR claude\-* " \(-> anthropic,"
.BR gemini\-* " \(-> google,"
.BR gpt\-* / o[0\-9]* " \(-> openai,"
.BR claude\-code[:tier|model] " \(-> Claude Code CLI,"
anything else \(-> ollama (e.g.
.BR minimax\-m2:cloud ")."
Direct pass-through examples:
.BR claude\-opus\-4\-6 ","
.BR gemini\-2.5\-pro ","
.BR minimax\-m2:cloud "."
The
.B BCS_<BACKEND>_MODEL
environment variables still take precedence over
.B \-m
when set. Note: Ollama models whose names happen to match
.BR claude\-* ", " gemini\-* ", " gpt\-* " or " o[0\-9]*
are unreachable through
.B \-m
\(em rename the local model if you need to target it.
.TP
.BR \-e ", " \-\-effort " " \fILEVEL\fR
Analysis depth:
.BR low " (clear violations only),"
.BR medium " (violations and significant warnings; default),"
.BR high " (all violations and warnings),"
.BR max " (exhaustive line-by-line audit)."
Controls both the prompt guidance and output token budget.
.B medium
is the recommended default for all backends.
.B high
improves results for Claude backends but is marginal or harmful for others.
.B max
should be avoided for Ollama cloud models (increases hallucination risk).
.TP
.BR \-s ", " \-\-strict
Treat warnings as violations.
.TP
.BR \-S ", " \-\-no\-strict
Don't treat warnings as violations (default).
.TP
.BR \-T ", " \-\-tier " " \fITIER\fR
Report only findings at this tier
.RB ( core ", " recommended ", " style ).
.TP
.BR \-M ", " \-\-min\-tier " " \fITIER\fR
Report findings at this tier or higher severity
.RB ( core ", " recommended ", " style ).
.TP
.BR \-j ", " \-\-json
Emit findings as a single JSON object on stdout. The schema mirrors
.B shellcheck \-\-format=json1
with a
.B {source, meta, comments}
envelope so CI tooling that already consumes shellcheck JSON can ingest
.B bcs check
findings with minimal adjustment. Info messages still go to stderr when
verbose; stdout is JSON\-only. Exit code 5 is returned when the LLM emits
invalid JSON (the raw response is preserved in
.BR $BCS_RESPONSE_DUMP ).
Each comment object carries
.BR line ", " endLine ", " level " (error|warning|info), "
.BR code " (integer), "
.BR bcsCode " (full BCS#### string), "
.BR tier ", " message ", and "
.BR fixSuggestion .
.TP
.BR \-D ", " \-\-debug
Announce the raw-response dump path on success (the dump is always written
and auto-announced on failure).
.TP
.BR \-v ", " \-\-verbose
Show info messages (default).
.TP
.BR \-q ", " \-\-quiet
Suppress info messages.
.TP
.BR \-h ", " \-\-help
Show check help and exit.
.PP
Every API response is saved to
.IR ${XDG_STATE_HOME:\-~/.local/state}/bcs/last\-response.txt
(or
.I /tmp/bcs\-last\-response.XXXXXX
via mktemp if no state directory). The Claude Code CLI backend does not
dump \(em it returns text directly, not JSON.
.PP
Inline suppression:
.B #bcscheck disable=BCS\fIxxxx\fR
on its own line suppresses the named rule for the next command or block,
matching the scope rules of
.B shellcheck
directives.
.\"
.SS bcs codes
List all BCS rule codes and titles extracted from section files plus any
user rule drop-ins
.RI ( data/98\-user.md ", " data/98\-user.d/*.md ).
Each code follows the format
.B BCS\fISSRR\fR
where
.I SS
is the section number and
.I RR
is the rule number, both zero-padded. Output is decorated with the rule's
effective tier (default tier overridden by
.IR policy.conf ,
if any).
.TP
.BR \-T ", " \-\-tier " " \fITIER\fR
Show only rules at this tier
.RB ( core ", " recommended ", " style ", " disabled ).
.TP
.BR \-E ", " \-\-explain " " \fIBCS####\fR
Print the full body of a single rule (heading, tier, rationale, examples)
and exit. Useful for drilling into a specific rule after a failed
.B bcs check
run.
.TP
.BR \-p ", " \-\-plain
Omit tier decoration (output is just "BCS#### Title").
.TP
.BR \-x ", " \-\-exclude\-disabled
Skip rules that have been disabled via
.IR policy.conf .
.TP
.BR \-h ", " \-\-help
Show codes help and exit.
.\"
.SS bcs generate
Regenerate
.I BASH\-CODING\-STANDARD.md
from the individual section source files
.RI ( data/[0-9]*.md ).
A table of contents header is prepended automatically.
.TP
.BR \-o ", " \-\-output " " \fIFILE\fR
Output file (default:
.IR data/BASH\-CODING\-STANDARD.md ).
.TP
.BR \-h ", " \-\-help
Show generate help and exit.
.\"
.SS bcs help
Show help for a command. With no argument, shows the main help summary.
.\"
.SH OPTIONS
Global options recognized before any subcommand:
.TP
.BR \-V ", " \-\-version
Display version information and exit.
.TP
.BR \-v ", " \-\-verbose
Enable verbose output (default).
.TP
.BR \-q ", " \-\-quiet
Suppress info messages.
.TP
.BR \-h ", " \-\-help
Display main help message and exit.
.\"
.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
General error.
.TP
.B 2
Usage error (unknown command, unexpected argument).
.TP
.B 3
File not found (standard document, data directory, template, or script).
.TP
.B 13
Permission denied (cannot read script file).
.TP
.B 5
I/O error (API connection or request failure).
.TP
.B 18
Missing dependency (no LLM backend available, or required tool not found).
.TP
.B 22
Invalid argument or option (EINVAL).
.\"
.SH CONFIGURATION
.B bcs
sources configuration files as Bash in cascade order (BCS0111). Later files
override earlier ones key-by-key, so a user file may set only the values it
wants to change and inherit the rest from system defaults:
.PP
.RS
.I /etc/bcs.conf
.br
.I /etc/bcs/bcs.conf
.br
.I /usr/local/etc/bcs/bcs.conf
.br
.I ~/.config/bcs/bcs.conf
.RE
.PP
CLI flags override config file settings; config overrides environment variables.
See
.I bcs.conf.sample
for all available variables.
.\"
.SH ENVIRONMENT
These variables can be set in the config file or environment.
CLI flags take precedence.
.TP
.B BCS_MODEL
Default quality tier or model name (fast, balanced, thorough, or a direct
model ID such as claude-sonnet-4-6, minimax-m2:cloud, claude-code, etc.).
Overridden by
.BR \-m .
.TP
.B BCS_EFFORT
Default analysis depth (low, medium, high, max). Overridden by
.BR \-e .
.TP
.B BCS_STRICT
Treat warnings as violations (0 or 1). Overridden by
.BR \-s / \-S .
.TP
.B BCS_JSON
Default JSON output mode (0 or 1). Overridden by
.BR \-j / \-\-json .
.TP
.B BCS_OLLAMA_MODEL
Override the Ollama model name instead of using the tier-based default.
.TP
.B BCS_ANTHROPIC_MODEL
Override the Anthropic model name instead of using the tier-based default.
.TP
.B BCS_GOOGLE_MODEL
Override the Google model name instead of using the tier-based default.
.TP
.B BCS_OPENAI_MODEL
Override the OpenAI model name instead of using the tier-based default.
.TP
.B OLLAMA_HOST
Ollama server address (default: localhost:11434).
.TP
.B ANTHROPIC_API_KEY
Anthropic API key for the anthropic backend.
.TP
.B GOOGLE_API_KEY
Google API key for the google (Gemini) backend.
.TP
.B GEMINI_API_KEY
Alternative Google key. If both
.B GOOGLE_API_KEY
and
.B GEMINI_API_KEY
are set,
.B GEMINI_API_KEY
is unset and
.B GOOGLE_API_KEY
is used.
.TP
.B OPENAI_API_KEY
OpenAI API key for the openai backend.
.TP
.B TMPDIR
Used by the
.B check
subcommand (claude backend) for temporary working directories. Falls back to
.IR /tmp .
.\"
.SH FILES
.TP
.I /usr/local/bin/bcs
Installed CLI binary.
.TP
.I /usr/local/bin/bcscheck
Convenience shim for bcs check; defaults via config file.
.TP
.I /usr/local/share/yatti/BCS/data/
Installed standard document and section files.
.TP
.I /usr/local/share/yatti/BCS/examples/templates/
Script template files.
.TP
.I /etc/bash_completion.d/bcs
Bash tab-completion for bcs.
.TP
.I /etc/bash_completion.d/bcscheck
Bash tab-completion for bcscheck.
.TP
.I /usr/local/share/man/man1/bcs.1
This manual page.
.\"
.SH EXAMPLES
.TP
.B bcs
View the standard (formatted if terminal, plain otherwise).
.TP
.B bcs display \-c
View the standard as plain text.
.TP
.B bcs template \-t complete
Generate a full-featured script template to stdout.
.TP
.B bcs template \-t minimal \-n deploy \-o deploy.sh \-x
Generate a minimal template, save to file, make executable.
.TP
.B bcs template \-t library \-n auth \-o lib\-auth.sh
Generate a sourceable library template.
.TP
.B bcs check myscript.sh
Run AI-powered compliance check (auto-detects backend).
.TP
.B bcs check \-m minimax\-m2:cloud myscript.sh
Check using local Ollama with a specific cloud model.
.TP
.B bcs check \-m claude\-code myscript.sh
Check using the Claude Code CLI at the balanced tier.
.TP
.B bcs check \-\-strict deploy.sh
Strict mode: treat warnings as violations.
.TP
.B bcs codes
List all BCS rule codes and titles.
.TP
.B bcs generate
Regenerate BASH\-CODING\-STANDARD.md from section files.
.TP
.B bcs help template
Show detailed help for the template subcommand.
.\"
.SH ACCURACY
Backend accuracy varies significantly. Based on the 2026-04-17 refresh
covering four BCS-compliant scripts of varying complexity
.RB ( cln ", " md2ansi ", " which ", " tests/accuracy/bcs\-check\-accuracy.sh )
across six models \(mu three effort levels (60 completed runs; 12
.BR glm\-5.1:cloud
runs failed HTTP 403 and are excluded). See
.I tests/accuracy/LLM\-ACCURACY.md
for the full scoring matrices.
.PP
.B Recommended configurations
.RS
.TP
.B Quick sanity check
gpt\-5.4 at medium effort (9\(en71s; 0\(en1 FP on most scripts, noisier on
function-free scripts)
.TP
.B Daily development
claude\-sonnet\-4\-6 at medium effort (35\(en83s; zero false positives across
all four test scripts; reliable suppression handling)
.TP
.B Pre-commit review
claude\-sonnet\-4\-6 at high effort (43\(en101s; more findings; still zero FPs
on most scripts)
.TP
.B Thorough audit
claude\-sonnet\-4\-6 at max effort (42\(en128s; top scorer on md2ansi and
tests/accuracy/bcs\-check\-accuracy.sh)
.TP
.B Pre-release audit
claude\-code at max effort (deepest
.B which
analysis; very slow at 5\(en14 min on larger scripts)
.RE
.PP
.B Backend ranking (2026-04-17 refresh)
.RS
.IP 1. 4
Anthropic API (claude\-sonnet\-4\-6) \(em best speed/accuracy ratio and most
consistent across script types. Only model to find both missing
.B local \-\-
separators and both
.B ((FLAG == 0))
sites. Recommended for daily development.
.IP 2. 4
Claude Code CLI \(em deepest rule citation on suppression/fence patterns.
Tradeoff: very slow (5\(en14 min on larger scripts). Best for final pre-release
audits.
.IP 3. 4
OpenAI API (gpt\-5.4) \(em fastest backend (4\(en109s). Best for quick checks.
Degrades on function-free scripts (misapplies BCS0202). Avoid
.B max
effort \(em introduces false positives without adding coverage.
.IP 4. 4
Google API (gemini) \(em not included in the 2026-04-17 refresh matrix.
Prior guidance stands:
.B thorough
tier at
.B medium
effort is reliable; lower tiers over-report.
.IP 5. 4
Ollama cloud models \(em not recommended for accuracy-sensitive work.
.BR minimax\-m2.7:cloud
and
.BR qwen3\-coder:480b\-cloud
score 0\(en2/3 per script with persistent 2\(en6 FPs per run.
.BR glm\-5.1:cloud
is currently unavailable (HTTP 403 "a subscription is required for access"
via ollama.com).
.RE
.PP
Tier keywords
.RB ( fast ", " balanced ", " thorough )
probe backends in order. When an Ollama server is running, it is probed
first \(em this may route tier keywords to low\-accuracy cloud models.
Use explicit model names (e.g.
.BR \-m\ gpt\-5.4 " or " \-m\ claude\-sonnet\-4\-6 )
for predictable quality.
.\"
.SH SEE ALSO
.BR bash (1),
.BR shellcheck (1),
.BR bcscheck (1)
.\"
.SH AUTHORS
Developed by Okusi Associates for the Indonesian Open Technology Foundation (YaTTI).
.\"
.SH LICENSE
The \fBbcs\fR program \(em including the CLI scripts, tests, Makefile,
templates, and man pages \(em is licensed under the GNU General Public
License version 3 or later (GPL\-3.0\-or\-later).
The Bash Coding Standard document distributed in
\fI/usr/share/yatti/BCS/data/\fR is licensed under
Creative Commons Attribution\-ShareAlike 4.0 International (CC BY\-SA 4.0).
Bundled reference implementations under \fIexamples/lib/\fR ship with
their own per\-project LICENSE files.