bcs.1

.\" BCS Manual Page
.\" Generated: 2026-07-10
.\"
.TH BCS 1 "September 2026" "BCS 2.0.8" "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
.RI [ OPTIONS ]
.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
100 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 " (~18 lines),"
.BR basic " (~47 lines, default),"
.BR complete " (~119 lines),"
.BR library " (~48 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
Model alias or canonical model ID. Aliases (e.g.
.BR sonnet ", " opus ", " haiku ", " flash ", " pro ", " gpt5 )
are expanded via the
.B MODEL_ALIASES
associative array (defined in the script and overridable in
.IR bcs.conf )
and the result is routed by name prefix:
.BR claude\-* " \(-> anthropic,"
.BR gemini\-* " \(-> google,"
.BR gpt\-* / o[0\-9]* " \(-> openai,"
.BR claude\-code[:alias|model] " \(-> Claude Code CLI,"
anything else \(-> ollama (e.g.
.BR minimax\-m2:cloud ")."
Default is
.BR sonnet
(claude\-sonnet\-4\-6).
Direct pass-through examples:
.BR claude\-opus\-4\-8 ","
.BR gemini\-2.5\-flash ","
.BR minimax\-m2:cloud "."
The legacy tier keywords
.BR fast ", " balanced ", " thorough
are no longer accepted and exit non\-zero with a migration hint pointing at the alias map.
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; alias " min ";"
short scripts only \(em on real-size scripts it raised false [ERROR] findings
in every measured run, so do not gate a build on it),
.BR medium " (violations and significant warnings; default),"
.BR high " (all violations and warnings),"
.BR xhigh " (comprehensive audit, every finding however minor),"
.BR max " (exhaustive line-by-line audit)."
Controls output token budget AND thinking/reasoning depth on capable models.
Anthropic takes one of two incompatible shapes, chosen by model: a
.B thinking.budget_tokens
count on
.BR haiku\-4\-5 / sonnet\-4\-5 / sonnet\-4\-6 / opus\-4\-5 / opus\-4\-6 ", "
or adaptive thinking plus
.B output_config.effort
\(em the
.B \-e
word itself, not a token count \(em on
.BR opus\-4\-7 / opus\-4\-8
and every Claude 5.
OpenAI
.B reasoning_effort
on
.BR o[0\-9]* / gpt\-5* ", "
Google
.B thinkingConfig.thinkingBudget
on the 2.5 family (except
.BR gemini\-2.5\-flash\-lite )
and
.BR gemini\-3.5\-flash* "."
A model matching no gate is sent no thinking field at all, rather than a
guess: the wrong shape is answered with HTTP 400, not a silent downgrade.
.B medium
is the recommended default for all backends.
.B high
improves results for Claude/OpenAI reasoning models but is marginal elsewhere.
.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 .
.B tier
and
.B level
are not taken from the model: both are recomputed locally from the
.B **Tier:**
field of the cited rule (honouring
.BR policy.conf ),
so the severity that drives the exit code cannot be wrong because the model
mislabelled a finding. Under
.B \-\-strict
every recomputed level is
.BR error .
A finding citing a rule that
.B policy.conf
sets to
.B disabled
is dropped from the output; a finding citing a code with no tier of its own
keeps whatever level the model gave it.
.TP
.BR \-\-shellcheck ", " \-\-no\-shellcheck
Enable (default) or disable the
.B shellcheck \-\-format=json \-x
static-analysis prelude that is prepended to the LLM prompt as deterministic
context. Disable globally with
.BR BCS_SHELLCHECK=0 .
.TP
.BR \-\-cache ", " \-\-no\-cache
Enable (default) or disable the result cache. Successful check results are
stored under
.I ${XDG_CACHE_HOME:\-~/.cache}/bcs/
keyed on script content, standard content, model, effort, and all filters,
so re-checking unchanged inputs returns instantly at zero API cost. Any
change to an input produces a new key.
.B \-\-no\-cache
bypasses the cache entirely (no read, no write). Disable globally with
.BR BCS_CACHE=0 .
The cache directory may be deleted at any time.
.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 returns
text directly (not JSON), so for that backend the dump holds the CLI's
standard error (an authentication or quota failure shows up there); with
.BR \-\-json ,
an invalid response is still preserved in the dump file. A CLI that exits
non-zero is reported as exit 5, never as exit 1.
.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 \-J ", " \-\-json
Emit the rule list as a JSON array of
.B {code, title, tier, section, disabled}
objects (requires
.BR jq ).
Honours the same
.BR \-T " and " \-x
filters as text mode.
.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 ),
joined with horizontal-rule separators. User rules in
.IR data/98\-user.md " and " data/98\-user.d/*.md
are spliced in after section 12, before the coda. The output file is
written read-only (mode 444) to discourage direct edits.
.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; for
.B check
in text mode, at least one finding tagged [ERROR]. Text mode asks for one
finding per line, shaped "[ERROR|WARN] BCSxxxx line N: <defect>. Fix: <remedy>",
and nothing else. A compliant script prints the
single line "No BCS violations found." and exits 0. Only a finding header
promotes the exit code; a sentence that merely mentions [ERROR] does not.
.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, invalid JSON in
.B \-\-json
mode, or a completion with no text (the finish reason is reported).
An empty completion is never reported as a clean pass and is never cached.
.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 model alias or canonical name (e.g. sonnet, opus, gpt5,
claude-sonnet-4-6, minimax-m2:cloud, claude-code, etc.). Default
.BR sonnet "."
Overridden by
.BR \-m .
.TP
.B BCS_EFFORT
Default analysis depth (low|min, medium, high, xhigh, 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_SHELLCHECK
Enable (1, default) or disable (0) the shellcheck static-analysis prelude.
Overridden by
.BR \-\-shellcheck / \-\-no\-shellcheck .
.TP
.B BCS_CACHE
Enable (1, default) or disable (0) the result cache. Overridden by
.BR \-\-cache / \-\-no\-cache .
.TP
.B BCS_TIER
Default tier filter (core, recommended, style). Overridden by
.BR \-T .
.TP
.B BCS_MIN_TIER
Default minimum-tier filter (core, recommended, style). Overridden by
.BR \-M .
.TP
.B BCS_DEBUG
Announce the raw-response dump path on success (0 or 1). Overridden by
.BR \-D .
.TP
.B BCS_RESPONSE_DUMP
Override the raw-response dump file path.
.TP
.B MODEL_ALIASES
Bash associative array; extend or override the built-in alias map in
.IR bcs.conf
(e.g.
.BR "MODEL_ALIASES[mymodel]=qwen3.5:14b" ").
The four legacy
.BR BCS_<BACKEND>_MODEL
overrides are gone \(em set the alias instead.
.TP
.B OLLAMA_HOST
Ollama server address (default: localhost:11434).
.TP
.B BCS_OLLAMA_NUM_CTX
Ollama context window in tokens, sent as
.B options.num_ctx
(default: 40960). Without it the server truncates the prompt to its 4096-token
default and the model never sees the standard. It must hold the standard
(about 33k tokens) plus the script plus the reply; raise it for long scripts or
.B \-e high
and above.
.TP
.B BCS_OLLAMA_KEEP_ALIVE
How long Ollama keeps the model loaded after a check: a duration such as
.B 30m
or
.BR 1h ,
or seconds as an integer (\-1 = forever). Default: 30m.
.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 ${XDG_CACHE_HOME:\-~/.cache}/bcs/
Result cache for
.BR "bcs check" ;
safe to delete at any time.
.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 using the default
.B sonnet
alias (claude-sonnet-4-6 via the Anthropic API).
.TP
.B bcs check \-m sonnet \-e medium myscript.sh
Equivalent to the bare form above; alias \(-> canonical name \(-> backend.
.TP
.B bcs check \-m gpt5 \-e high deploy.sh
OpenAI gpt-5 with reasoning_effort=medium.
.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 with the default
.B sonnet
alias.
.TP
.B bcs check \-m claude\-code:opus myscript.sh
Check using the Claude Code CLI with opus.
.B \-e
has no effect on this backend: the CLI always runs at its lowest native
effort, with no MCP servers loaded.
.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
.B \-m gpt5 \-e medium
(9\(en71s; 0\(en1 FP on most scripts, noisier on function-free scripts)
.TP
.B Daily development
.B \-m sonnet \-e medium
(35\(en83s; zero false positives across all four test scripts; reliable suppression handling)
.TP
.B Pre-commit review
.B \-m sonnet \-e high
(43\(en101s; more findings; still zero FPs on most scripts)
.TP
.B Thorough audit
.B \-m sonnet \-e max
(42\(en128s; top scorer on md2ansi and tests/accuracy/bcs\-check\-accuracy.sh)
.TP
.B Pre-release audit
.B \-m claude\-code:opus \-e max
(deepest 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 / alias
.BR gpt5 )
\(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 \-m pro
(then gemini-2.5-pro, since retired by Google;
.B pro
now expands to gemini-3.1-pro-preview, not yet measured) at medium effort was reliable; smaller models in the family
(flash, flash-lite) 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
Use a built-in alias (e.g.
.BR \-m\ sonnet ", " \-m\ opus )
or a canonical model ID (e.g.
.BR \-m\ gpt\-5 ", " \-m\ claude\-sonnet\-4\-6 )
for predictable quality. Add custom aliases via
.B MODEL_ALIASES[name]=canonical-id
in
.IR bcs.conf "."
.\"
.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.