@open-nav/cli

Command line access to the NAV Online Számla invoice service.

npx @open-nav/cli --help
# or
npm install -g @open-nav/cli && open-nav --help

Configuration

Credentials come from the environment, or from a .env file found by walking up from the working directory. They are never accepted as command line arguments: that would put them in shell history, in process listings, and in the transcript of any agent that ran the command.

cp .env.example .env   # then fill it in
open-nav config        # shows what is set, masks the secrets
open-nav token         # end-to-end check: are the credentials real?

open-nav help config lists every variable.

Built for scripts and agents

• JSON by default when stdout is not a terminal. No flag to remember; a human at a terminal still gets readable text. --json and --pretty override.
• One envelope for every result, so a caller can branch on ok alone:

  { "ok": true, "command": "validate", "data": { "valid": true } }

• Exit codes that mean something: 0 ok, 2 usage or configuration, 3 the document failed local validation and was not sent, 4 NAV rejected it, 5 no verdict reached (network, timeout, still processing).
• --describe prints the whole command surface as JSON — names, usage, options, exit codes, and whether each command needs credentials. An agent can discover what the tool can do without a man page.

open-nav --describe | jq '.commands[] | select(.needsCredentials == false)'

Commands

| Command | Needs credentials | What it does | | -------------------------- | ----------------- | ---------------------------------------------------------- | | config | no | Report which variables are set, masking secrets | | validate <file> | no | Check an invoice against schema and business rules | | fault <CODE> | no | Look up NAV's description of a fault code | | token | yes | Exchange credentials for a token — the quickest smoke test | | taxpayer <taxNumber> | yes | Look up a taxpayer; accepts the 11 digit written form | | submit <file...> | yes | Validate, then submit; --wait polls for the verdict | | status <transactionId> | yes | Processing status; --wait polls to a verdict | | digest --from --to | yes | List invoices issued or received in a date range | | invoice <number> | yes | Fetch one invoice in full; --xml prints the XML | | transactions --from --to | yes | List data submissions in a time window |

Validating without credentials

validate and fault contact nothing. They are useful before you have a technical user at all, and they are the fastest way to find out why NAV rejected something:

open-nav validate invoice.xml --operation CREATE --pretty

invoice.xml: invalid (1 error, 0 warnings)

  error  INCORRECT_SUMMARY_CALCULATION_INVOICE_VAT_AMOUNT_SUMMARY
         invoiceSummary.summaryNormal.invoiceVatAmount
         is 280000.00 but the lines total 280800.00
         NAV: The amount of the tax VAT rates differs from the VAT of the invoice.

Findings carry NAV's own fault code and wording, in en, hu or de via --language, so a local failure reads like the rejection it prevents.

submit validates before sending by default and refuses to submit a document with errors — a rejection costs a round trip and consumes the requestId. --skip-validation overrides that if you need it.

Licence

MIT. Not affiliated with NAV.