Writing a Script-Friendly CLI: Exit Codes, stdout vs stderr, JSON Output, TTY Detection and Signals
Why does a CLI that works perfectly by hand quietly produce wrong results inside a pipeline? Practical rules and Go examples for exit codes, stdout vs stderr, machine-readable output, terminal detection, signals and broken pipes.
A command line tool has two kinds of users: the person typing in a terminal, and the script, CI job or other program that calls it. Tools written with only the first user in mind tend to betray the second. They exit zero on failure, print progress bars into redirected output, corrupt JSON with color escapes and leave half-written files behind on Ctrl-C. The result is familiar: the tool works perfectly when you try it by hand and quietly produces wrong results the moment it lands in a pipeline. This post covers the contract that makes a CLI safe to automate, with Go examples for each piece.
The contract has four channels
A CLI talks to the outside world through its exit code, standard output, standard error and the signals it receives. If a script author can trust all four, your tool ends up in automation. If one of them is unreliable, people wrap it in workarounds and eventually replace it.
Exit codes are the only signal that matters
The shell, set -e, CI runners and process supervisors look at the exit code and nothing else. Nobody parses your error message. So the first rule is simple: every failure path exits non-zero.
A useful convention:
0 for success.
1 for a general failure: the operation was attempted and did not work.
2 for usage errors such as an unknown flag or a missing argument. Go's standard flag package exits with 2 on parse errors, so this is an established convention.
130 when interrupted with Ctrl-C. Shells report 128 plus the signal number, and SIGINT is 2.
If you want more meaning than that (a separate code for "nothing changed", say), document it and never change it. grep returns 1 for no match and 2 for an error, and scripts have relied on that distinction for decades.
The classic Go trap is os.Exit. It does not run deferred functions. If main defers closing a file, removing a temp directory or flushing a buffer, and some error path calls os.Exit(1), the cleanup never happens. log.Fatal does the same thing internally. The fix is to move all the work into a function that returns an error and exit in exactly one place:
Every defer inside run now executes when run returns, and the exit comes afterwards. Note that the interruption is recorded before calling stop(): stop also cancels the context, so checking afterwards would make every error look like an interrupt. usageError is a small error type you define yourself. The second benefit is testability. You can call run with arguments and two buffers and assert on output and error directly, without spawning a subprocess.
stdout is for data, stderr is for humans
Only the data your tool produces goes to standard output. Progress, warnings, summaries like "processed 3 files" and error messages go to standard error. The reason is redirection. Someone running tool list > out.txt or tool list | jq wants only the data in the file or pipe, and still wants to see progress in the terminal. Mixing the two either corrupts the data or hides what is happening.
The robust way to enforce this is the pattern above: pass two separate io.Writer values into run. Writing to an injected writer instead of calling fmt.Println everywhere makes it hard to use the wrong stream, and lets tests capture each one separately.
One more detail: if you buffer stdout with bufio.Writer, call Flush before exiting and check the error it returns. A full disk or a closed pipe surfaces exactly there. Ignore it and the tool emits truncated output and exits zero.
Machine-readable output is a separate interface
An aligned table is pleasant to read, but when a script parses it with awk, every change in column width breaks something. Offer a second format: --json or --output json. Here is a firm opinion: do not pass off columnar plain text as "machine readable". Emit real JSON. JSON tolerates added fields without breaking old parsers, and values with spaces, newlines or Unicode stop being a problem.
JSON output is a contract too:
Keep field names and types stable. Renaming a header in the human table is fine; renaming a JSON field is a breaking change.
For long lists, consider one JSON object per line (JSON Lines). Consumers can stream it, and you do not have to hold the whole result in memory.
Never leave half a JSON document on stdout when something fails. Either write a valid document or write nothing; the error itself belongs on stderr and in the exit code.
Terminal or pipe?
Colors, progress bars, interactive confirmations and pagers only make sense when a human is watching. You find out by checking whether the stream is attached to a terminal. In Go, term.IsTerminal(int(os.Stdout.Fd())) from golang.org/x/term answers that.
Rules worth following:
Enable color only when the target stream is a terminal, and decide separately for stdout and stderr; with tool 2>errors.log, stdout may still be a terminal.
Disable color when the NO_COLOR environment variable is set to a non-empty value. It is a widely adopted convention. Also offer --color=always|never|auto so people who want color in CI logs can have it.
Before asking for confirmation, check that standard input is a terminal. If it is not, fail and require an explicit flag such as --yes. Otherwise the tool either waits for input forever in CI or treats empty input as consent.
Draw progress on stderr, and skip it entirely when stderr is not a terminal. A CI log full of carriage returns is unreadable.
Signals and half-finished work
Ctrl-C sends SIGINT; container runtimes and supervisors send SIGTERM when stopping a process. By default Go terminates immediately and no deferred calls run. The signal.NotifyContext call above turns those signals into context cancellation. Every long-running operation should take that context and return cleanly when it is cancelled: network calls via http.NewRequestWithContext, loops by checking ctx.Err() on each iteration.
The answer to half-written files is atomic writes. Write to a temporary file in the same directory as the target, call Sync, close it, and only if everything succeeded os.Rename it over the target. A rename within one filesystem either happens completely or not at all, so an interrupted run leaves the old file intact. Creating the temp file under os.TempDir breaks this when the target lives on a different filesystem, because the rename then fails; that is why the same directory matters.
Think about the second Ctrl-C as well. If cleanup is slow, the user presses it again. Once the stop function returned by NotifyContext has been called, the signal goes back to its default behavior. The context.AfterFunc(ctx, stop) line in the example (Go 1.21 and later) does that on the first signal: the first press starts a graceful shutdown, the second one kills the process. That is what users expect. Without it, a stuck cleanup step swallows Ctrl-C and kill -9 becomes the only way out.
Broken pipes
When you run tool list | head -n 5, head exits after five lines and your tool keeps writing to a closed pipe. If the program has not installed its own handler for SIGPIPE, the Go runtime terminates it with SIGPIPE on such a write to stdout or stderr. That is usually correct, and shells do not treat it as a failure. The problem appears in code that catches SIGPIPE with signal.Notify, or listens for all signals: now the write returns EPIPE, the tool reports it as an ordinary error and exits with 1, and scripts with set -o pipefail fail for no good reason. Do not catch SIGPIPE unless you have a deliberate reason; if you do, treat syscall.EPIPE as a quiet exit.
When not to bother
For a throwaway helper that only you will ever run, most of this discipline is overkill. Correct exit codes are still mandatory, because someone will eventually put it in a script. If your tool is fully interactive (a full-screen terminal UI), offering separate non-interactive subcommands is cleaner than bolting machine output onto the UI. And resist adding many output formats: human text plus JSON covers most tools, while YAML, CSV and templating each bring their own maintenance and testing cost.
Checklist
Before shipping, try these: tool bad-flag; echo $? should print 2. tool list > /dev/null should still show progress and warnings in the terminal. tool list --json | jq . should parse cleanly. tool list | head -n 1 should finish without printing an error. NO_COLOR=1 tool list should have no color. Ctrl-C in the middle of a long operation should leave the target file intact and exit with 130. A tool that passes these six checks will not make the scripts that depend on it quietly produce wrong results.
[OK] 30 records · 9 featured · 1 retainer · 20 standard
/02 services
services.tree
> note
· Prices are in USD. Volume discounts of 7% for 6-12 day projects and 14% for 13+ day projects apply. Programs of 100+ person-days are priced individually. Prices are negotiable based on scope, urgency and long-term collaboration.
> ls ~/products/ --open-source
[OK] 2 entries · 1 live · 1 pre-release
/03 products
products.list
liveopen source · mit/prod/01
filex
the self-hosted file manager that embeds anywhere
single go binary · vue/react/web-component embed · 5 storage drivers · realtime collab · rbac · native multi-tenancy · mcp server for ai agents
We build infrastructure, automate everything, and keep systems running.
BRF Tech is a Bursa-based DevSecOps and software consulting firm. We operate across 30 service areas, from Kubernetes cluster management to serverless platform setup, CI/CD pipeline design to AI agent development.
What we do is simple: we set up your systems, automate them, and make sure they won't wake you up at 3 AM. We codify your infrastructure with Terraform, move your deployments to GitOps with ArgoCD, and monitor everything with Prometheus. If something breaks — we intervene before it does.
We're against vendor lock-in. We work with open-source tools, self-hosted solutions, and industry-standard technologies. We build your own serverless platform on Knative, isolate with Kata Containers, manage your secrets with Vault. Every project is delivered with clear scope, clear timeline, clear pricing.
DevSecOps & CI/CD
Kubernetes & Serverless
Infrastructure as Code
AI & Agent (MCP/ACP)
Security & Zero Trust
Full-Stack Development
Self-Hosted Solutions
> grep -i question ~/faq.md
[OK] 3 entries · click to expand
[?]What services are included in BRF Tech's DevOps solutions?▾
We offer CI/CD pipeline setup, Kubernetes cluster management, container migration, infrastructure automation with Terraform, monitoring & alerting, in-house technology installations and DevOps consulting services.
[?]What are your software development services?▾
We offer MVP development, existing software performance optimization, backend API development (Node.js, Go, Python) and full-stack application development. Every project is delivered with minimal technical debt.
[?]Which DevOps tools do you work with?▾
From Kubernetes and Docker to Talos Linux, from Terraform and OpenTofu to Ansible, and across Jenkins, GitLab CI/CD, GitHub Actions, ArgoCD, Flux, Helm and Rancher, we work with industry-standard tooling. For observability and error tracking we use Prometheus, Grafana, Loki, Tempo, OpenTelemetry and GlitchTip; for networking, Cilium and Envoy; for test automation, Playwright, Cypress, k6, Locust, Testcontainers and Trivy. We determine the most suitable toolset together, based on your project’s needs.
Automated build, test and deployment pipelines with GitHub Actions, GitLab CI/CD.
Automated build, test and deploy pipeline setup for existing or new repositories. GitHub Actions, GitLab CI/CD or preferred tool is used. Separate workflows are defined for staging + production environments.
Container architecture migration, cluster setup and orchestration.
Production-ready Kubernetes cluster setup on bare-metal or cloud. Includes Helm charts, Ingress, TLS certificate management, namespace isolation and RBAC.
Cozystack is an open-source cloud platform built on Kubernetes and the VMware alternative we recommend most. Virtual machines run on KubeVirt, while managed PostgreSQL, MySQL, Redis and Kafka services and dedicated tenant Kubernetes clusters are provisioned from the same dashboard and API. Includes installation on your own bare-metal servers on Talos Linux, replicated storage with LINSTOR/DRBD, network isolation with Kube-OVN, tenant and quota structure, monitoring, backup and a disaster recovery plan. After deployment we also handle upgrades, operations and support; since the platform is open source, there are no license fees and no vendor lock-in.
Packages
Virtual machine support on an existing Kubernetes cluster with KubeVirt
$2,800
4–6 person-day
Pilot setup (3 nodes, virtual machines + managed database)
$3,500
5–8 person-day
Production setup (HA + replicated storage + monitoring + backup)
$6,500
10–16 person-day
Multi-tenant private cloud (tenants, quotas, managed service catalog)
Planned, low-downtime migration of vSphere/ESXi environments to Cozystack, OpenStack or VHI.
A planned move to a VMware alternative for environments whose costs rose after Broadcom moved VMware licensing to subscription bundles, or whose renewal is coming up. We start with an inventory of your vSphere/ESXi estate (virtual machines, disks, networks, dependencies), then compare today's license cost with the total cost of the target platform. In most environments the target is Cozystack; OpenStack fits large-scale IaaS needs and Virtuozzo Hybrid Infrastructure fits storage-heavy service providers. A pilot runs on non-critical virtual machines, disks are converted with tools such as virt-v2v and Forklift, and the migration proceeds in waves within maintenance windows, with a rollback plan for every step.
Packages
Inventory + cost comparison + migration plan
$2,400
3–5 person-day
Pilot migration (up to 10 virtual machines)
$3,500
5–8 person-day
Phased migration (up to 100 virtual machines)
$9,750
15–22 person-day
Full data center migration (network + storage + backup)
OpenStack deployment, Neutron networking, Ceph/Cinder storage, upgrades and operations.
OpenStack deployment and operations in your own data center. A containerized, highly available control plane with Kolla-Ansible; Nova (compute), Keystone (identity), Glance (images) and Horizon (dashboard). On the network side, Neutron with OVN, VLAN/VXLAN, provider and tenant networks, floating IPs and the Octavia load balancer; on the storage side, Cinder block storage on Ceph RBD and optional S3-compatible object storage. For existing deployments: health checks, planned upgrades between releases, monitoring and alerting setup, and a backup strategy.
Packages
Health check + improvement report (existing deployment)
$2,400
3–5 person-day
Lab / PoC setup (single region, 3 nodes)
$3,500
5–8 person-day
Release upgrade (existing deployment)
$3,900
6–10 person-day
Production setup (HA control plane + Ceph + Neutron/OVN)
Hyperconverged infrastructure: multi-tenant cloud plus block and S3-compatible storage for service providers.
Hyperconverged infrastructure with Virtuozzo Hybrid Infrastructure, where compute, storage and networking run on the same servers. Block, S3-compatible object and NFS storage on software-defined storage, plus backup storage (Backup Gateway) for backup products such as Acronis. For service providers: a multi-tenant cloud with domains and projects, quotas, a self-service panel and an OpenStack-compatible API. Includes hardware sizing, network design, cluster deployment and expansion, version upgrades and operations support.
Packages
Pre-deployment assessment + hardware sizing
$2,400
3–4 person-day
Version upgrade / cluster expansion
$2,800
4–6 person-day
Hyperconverged cluster setup (storage + compute)
$3,900
6–10 person-day
Service provider setup (multi-tenant cloud + S3 + backup storage)
Migration of existing applications to container architecture.
Migration of existing applications to container architecture. Docker image design, Compose configuration and conversion to Kubernetes manifests. Kata Containers / gVisor can be included for advanced isolation.
Health check of your current environment, capacity planning, platform selection and a roadmap.
An independent assessment of your current virtualization environment (VMware vSphere, OpenStack, VHI or other KVM-based platforms). The health check covers cluster configuration, resource overcommit, storage latency, forgotten snapshots, backup and patch status. Capacity planning measures CPU, memory and storage growth to work out the hardware you will need next. Platform selection decides which workload should run where: Cozystack for teams running containers and virtual machines side by side, OpenStack for large-scale IaaS, VHI for storage-heavy service providers; staying on the current platform is also an option for some workloads. The deliverable is a written report with a cost comparison and a prioritized roadmap.
In-house tools like GitLab, Nextcloud, VPN, mail server.
Installation of tools like GitLab, Mattermost, Nextcloud, mail server, VPN, internal monitoring on company servers. Deployed on Docker Compose or Kubernetes.
DB + cache + code bottleneck identification and resolution.
Profiling of existing application, identification and resolution of bottlenecks. DB query optimization, caching layer (Redis), service-level improvements.
MCP/ACP agents, RAG pipelines, multi-agent orchestration, model serving.
LLM integration (OpenAI, Claude, Gemini, local models), tool-augmented AI agents with MCP (Model Context Protocol) and ACP (Agent Communication Protocol). RAG pipeline, multi-agent orchestration, model serving (vLLM/Ollama). AI layer for existing business processes.
Event-driven data pipeline with Apache Kafka, RabbitMQ, NATS. ETL/ELT orchestration with Apache Airflow, real-time data streaming, CDC (Change Data Capture). Data lake/warehouse design, schema registry, dead letter queue management.
Packages
Kafka/RabbitMQ setup + basic producer/consumer
$3,500
5–7 person-day
ETL pipeline (Airflow + source → warehouse)
$5,200
8–12 person-day
Full event-driven architecture (CDC + streaming + DLQ)
Hands-on technical training for your teams. Docker & container fundamentals, Kubernetes operations, Terraform IaC, CI/CD best practices, AI/LLM integration workshops. Practical exercises in live lab environments, content customized by skill level.
E2E test automation with Playwright, Cypress, load testing with k6/Gatling. Pre-deploy quality gate integrated into CI/CD pipeline, test coverage reporting, visual regression testing. Reduce test writing time by up to 60% with AI-assisted test generation.
Your Collected Personal Data, Collection Method and Legal Basis
Any information that identifies or makes you identifiable is considered "personal data." When you visit our website or use our services, contact information such as your name, surname, email address, phone number, as well as your IP address and browser cookie data may be collected through automatic or semi-automatic means. This data is processed based on the legal grounds specified in Article 5 of the Personal Data Protection Law No. 6698: "being directly related to the establishment or performance of a contract" and "being mandatory for the legitimate interests of the data controller, provided that it does not harm the fundamental rights and freedoms of the data subject."
Purpose of Processing Your Personal Data
Your collected personal data is processed for the purposes of providing and improving our services, fulfilling customer requests, meeting legal obligations, conducting information security processes and managing communication activities. Your data is processed in a limited and proportionate manner for the stated purposes; when the purpose ceases to exist, data is deleted, destroyed or anonymized.
To Whom and For What Purposes Collected Personal Data May Be Transferred
Your personal data may be transferred to public institutions and organizations as required by legal regulations, to our business partners and technical infrastructure providers for the purpose of delivering services, and to lawyers and consultants in legal disputes. Transfers are carried out in accordance with Articles 8 and 9 of the Law, with necessary technical and administrative measures in place.
Your Rights as a Data Subject
In accordance with Article 11 of Law No. 6698, you have the right to: learn whether your personal data is being processed; request information if it has been processed; learn the purpose of processing and whether it is used in accordance with its purpose; know the third parties to whom it is transferred domestically or abroad; request correction if it has been processed incompletely or incorrectly; request deletion or destruction within the framework of conditions set out in Article 7 of the Law; request that the operations carried out be notified to third parties to whom data has been transferred; object to any adverse result arising from the analysis of data exclusively through automated systems; and claim compensation for damages in case of unlawful processing. You may contact us through the communication channels on our website to exercise these rights.
Terms & Conditions
Terms & Conditions
1. Service Scope and Changes
BRF Tech conducts its software development, DevOps consulting, infrastructure setup and technical support services within the framework of these terms and conditions. The scope of service is determined separately for each project and finalized through mutual agreement. BRF Tech reserves the right to update the scope, pricing and technical details of its services, provided that prior notice is given.
2. Privacy Policy
Personal data collected within the scope of our services is processed in accordance with our Privacy Policy. For detailed information, please review our Privacy Policy page.
3. Service Usage and Responsibilities
Clients agree to use the provided services solely within legal and ethical boundaries. BRF Tech reserves the right to suspend or terminate services in the event of misuse, violation of third-party rights, or use for illegal activities. The client is responsible for the accuracy and currency of the information provided within the project scope.
4. Payment Terms
Payment terms are determined on a project basis and finalized through mutual agreement at the start of the project. Unless otherwise specified, invoices are payable within 15 days of project delivery. A monthly late payment interest of 2% may apply to overdue payments.
5. Cancellation and Refund Policy
Cancellation requests must be submitted in writing at least 7 days before the service start date. For projects already in progress, billing is based on the proportion of completed work. No refunds are issued for software and infrastructure components specifically developed within the project scope.