achcli

achcli

achcli is a command-line tool for displaying and manipulating Nacha-formatted ACH files in a human-readable format. It is part of the moov-io/ach project, which provides Go libraries for creating, parsing, and validating ACH files.

Features

• Describe ACH files in a readable format.
• Mask sensitive information (e.g., account numbers, names).
• Compare (diff) two ACH files.
• Reformat ACH files to other formats (e.g., JSON).
• Merge multiple ACH files.
• Flatten batches in ACH files.
• Validate ACH files with custom options.
• Check original raw ACH file and batch control totals with -validate-totals, or also run File.ValidateWith as the HTTP server does with -validate-file.
• Read input from stdin when a path is - (describe, -diff, -reformat, -validate-totals, -validate-file). -fix writes next to the input file, so it does not support stdin.
• Fix certain fields in ACH files (e.g., update Effective Entry Date).
• Pretty-print amounts and other values for better readability.

Installation

achcli is built using Go. You can install it directly from the source:

go install github.com/moov-io/ach/cmd/achcli@latest

Ensure your Go environment is set up (Go 1.21+ recommended).

Usage

achcli is a tool for displaying Nacha formatted ACH files in a human readable format.

USAGE
   achcli [-mask] [-pretty] [-validate opts.json] file.ach|-

EXAMPLES
  achcli -diff first.ach second.ach    Show the difference between two ACH files
  achcli -mask file.ach                Print file details with personally identifiable information partially removed
  achcli -reformat=json first.ach      Convert an incoming ACH file into another format (options: ach, json)
  achcli -reformat=json - < file.ach   Read the input from stdin instead of a file
  achcli -diff first.ach - < second.ach  Diff a file against stdin
  achcli -validate opts.json file.ach  Read an ACH File with the provided ValidateOpts
  achcli -validate-totals file.ach     Validate original raw ACH file and batch control totals
  achcli -validate-totals -reformat=json file.ach  Write JSON to stdout if original totals pass
  achcli -validate-totals - < file.ach   Validate original control totals from stdin
  achcli -validate-file -reformat=json file.ach  Write JSON to stdout if File.ValidateWith passes
  achcli -version                      Print the version of achcli (Example: v1.34.0)
  achcli 20060102.ach                  Summarize an ACH file for human readability

FLAGS
  -diff                        Compare two files against each other
  -fix                         Trigger fix tasks
  -flatten                     Flatten batches in each file
  -mask                        Mask/hide full account numbers and individual names
  -mask.accounts               Mask/hide full account numbers
  -mask.corrections            Mask/Hide Corrected Data in Addenda98 records
  -mask.names                  Mask/hide full individual names
  -merge                       Merge files before describing
  -pretty                      Display all values in their human readable format
  -pretty.amounts              Display human readable amounts instead of exact values
  -reformat string             Reformat an incoming ACH file to another format
  -skip-validation             Skip all validation checks
  -update-eed string           Set the EffectiveEntryDate to a new value
  -v                           Print verbose details about each ACH file
  -validate string             Path to config file in json format to enable validation opts
  -validate-file                Like -validate-totals, but check with File.ValidateWith as the HTTP server's validate endpoint does
  -validate-totals              Validate original raw ACH control totals; with -reformat write to stdout if they pass
  -version                     Print moov-io/ach cli version

Validation Options (-validate)

Provide a JSON file with validation options for custom ACH validation. Example opts.json:

{
  "RequireABAOrigin": true,
  "BypassOriginValidation": false,
  "BypassDestinationValidation": false,
  "CustomTraceNumbers": true,
  "CustomReturnCodes": true,
  "AllowZeroBatches": true,
  "AllowZeroEntries": true,
  "AllowMissingFileHeader": true,
  "AllowMissingFileControl": true,
  "SkipAll": false
}

Usage: achcli -validate opts.json file.ach

Checking original totals (-validate-totals)

achcli -validate-totals first.ach second.ach
achcli -validate-totals -validate opts.json first.ach
achcli -validate-totals -reformat=json first.ach
achcli -validate-totals -reformat=json - < file.ach

This command reads each original file and checks file and batch counts, entry hashes, and debit and credit totals. It exits with status 0 only when every input passes, or 1 when any input or configuration fails. Flag syntax errors retain status 2. Failures print to stdout as ERROR: <path>: .... It reports every failing path. Without -reformat it is quiet on success unless -v is set, and it does not write output files.

Only raw ACH input is supported. JSON is rejected because the existing JSON parser recalculates control totals. The checks come from the reader and File.ValidateTotals; they do not recalculate block counts or verify padding consistency.

Validation options still apply to the reader, but a stored file control record is required even when AllowMissingFileControl is set. SkipAll, UnequalAddendaCounts and -skip-validation are rejected because they waive validation or count checks. Version, transformation and presentation flags are also rejected: -version, -diff, -fix, -merge, -flatten, -update-eed, -mask and its variants, and -pretty and its variants. Help requested after selecting totals mode is a conflict. Existing commands, including ordinary help, keep their current behaviour when -validate-totals is absent.

With -reformat, it takes exactly one file, checks its totals, and writes the file to stdout as ach or json. If the totals fail, stdout is only the ERROR: line. -v does not add a summary line. JSON is the parsed in-memory file, including validateOpts when -validate was passed. ach is rewritten Nacha with LF line endings and 9-padding; Writer.Write still runs File.Validate(), so a file that passes totals can still fail to emit ACH.

Checking the whole file (-validate-file)

achcli -validate-file first.ach second.ach
achcli -validate-file -reformat=json - < file.ach

This works like -validate-totals, with the same inputs, options, exit codes and -reformat behaviour, but checks the file with File.ValidateWith, which the HTTP server's /files/{id}/validate endpoint uses. Beyond the reader's checks, that rejects batch numbers that don't ascend, unless AllowUnorderedBatchNumbers or CustomTraceNumbers is set.

Fixing Files (-fix)

Use -fix to modify ACH files. Currently supports updating the Effective Entry Date:

achcli -fix -update-eed=20260102 input.ach

This will create a fixed file and output its path.

Examples

Describe a File

achcli ppd-debit.ach

Output:

Describing ACH file 'ppd-debit.ach'

  Origin      OriginName               Destination  DestinationName          FileCreationDate  FileCreationTime
   121042882  My Bank Name              231380104   Federal Reserve Bank     190624            0000

  BatchNumber  SECCode  ServiceClassCode    CompanyName       DiscretionaryData     Identification  EntryDescription  EffectiveEntryDate  DescriptiveDate
  0000001      PPD      225 (Debits  Only)  Name on Account                         121042882       REG.SALARY        190625

    TransactionCode       RDFIIdentification  AccountNumber      Amount     Name                    IdentificationNumber  TraceNumber      Category
    27 (Checking Debit)   23138010            12345678           100000000  Receiver Account Name                         121042880000001  Forward

  ServiceClassCode    EntryAddendaCount  EntryHash   TotalDebits  TotalCredits  MACCode              ODFIIdentification  BatchNumber
  225 (Debits  Only)  000001             0023138010  100000000    0                                  12104288            0000001

  BatchCount  BlockCount  EntryAddendaCount  TotalDebitAmount  TotalCreditAmount
  000001      000001      00000001           100000000         0

Mask Sensitive Data

achcli -mask example.ach

Masks account numbers, names, etc.

Diff Two Files

achcli -diff file1.ach file2.ach

Shows differences in headers, batches, etc., using colored output.

Reformat to JSON

achcli -reformat=json input.ach > output.json

Merge and Flatten Files

achcli -merge -flatten file1.ach file2.ach

Merges files and flattens batches before describing.

License

Copyright © 2020 The Moov Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contributing

achcli is part of the moov-io/ach repository. Contributions are welcome! See the main repository for details.