Command Line Usage
Languages: English | Français
This page is the complete CLI reference. For guided explanations, see Configuration and History and resume.
On this page:
Syntax: ngPost (options)* (-i | --auto | --monitor )+
--help : Help: display syntax
-v or --version : app version
-c or --conf : use configuration file (if not provided, ngPost uses the per-user config path described below)
--disp_progress : display cmd progressbar: NONE (default), BAR or FILES
-d or --debug : display extra information
--fulldebug : display full debug information
-l or --lang : application language
--check : check nzb file (if articles are available on Usenet)
-q or --quiet : quiet mode (no output on stdout)
// structured post history & article-level resume (SQLite database)
// every option below accepts both the _ and - form (e.g. --history_show or --history-show)
--history : list the structured post history (add --json for machine-readable output)
--history_show <id> : show the details of one history post
--history_import_csv <file> : import a legacy POST_HISTORY csv into the database
--regenerate_nzb <id> : regenerate an nzb from the history (use -o to set the output path)
--include_password : include the stored archive password in regenerated/shown output
--post_db <file> : path to the structured SQLite history database
--export_post_info <id> : write the post info file of a post from history (-o file, or stdout)
--resume_list : list resumable or partial posts (add --json)
--resume_check <id> : show the resume status for one post
--resume_post <ids> : resume one or several post ids (coma separated)
--resume_all : resume all resumable posts
--resume_abandon <id> : mark an incomplete post as abandoned (requires --yes)
--resume_purge <id> : purge the technical resume data of a post (requires --yes)
--dry_run : simulate a resume command without actually posting
--yes : assume yes for non-interactive destructive commands
--json : emit JSON output for script usage
// automated posting (scanning and/or monitoring)
--auto : parse directory and post every file/folder separately. You must use --compress, should add --gen_par2, --gen_name and --gen_pass
--monitor : monitor directory and post every new file/folder. You must use --compress, should add --gen_par2, --gen_name and --gen_pass
--rm_posted : delete file/folder once posted. You must use --auto or --monitor with this option.
// quick posting (several files/folders)
-i or --input : input file to upload (single file or directory), you can use it multiple times
-o or --output : output file path (nzb)
-x or --obfuscate : obfuscate the subjects of the articles (CAREFUL you won't find your post if you lose the nzb file)
-g or --groups : newsgroups where to post the files (coma separated without space)
-m or --meta : one of your fields, written in the post info file AND published in the nzb header (typically "password=qwerty42")
--post_meta : one of your fields, written in the post info file only, never published in the nzb (ex: "title=Photo backup 2026")
-f or --from : poster email (random one if not provided)
-a or --article_size: article size (default one: 716800)
-z or --msg_id : msg id signature, after the @ (default one: ngPost)
-r or --retry : number of time we retry to an Article that failed (default: 5)
-t or --thread : number of Threads (the connections will be distributed amongs them)
--gen_from : generate a new random email for each Post (--auto or --monitor)
// post info files, post commands and nzb upload
--post_info_template: template file used to write a post info file next to the nzb
--post_info_output : where to write the post info file (variables allowed)
--no_post_info : write no post info file for this run, whatever the config says (your --meta fields are still published in the nzb)
--post_info_only_on_success: only write the post info file when the post fully succeeded (default)
--no_post_info_only_on_success: write the post info file even for a failed or partial post
--nzb_post_cmd : command to run at the end of each post, repeatable; replaces the ones from the config file
--post_cmd_timeout : seconds before a stuck post command is killed (0: no limit)
--post_cmd_fail_is_error: a failed post command makes ngPost exit with an error
--no_post_cmd_fail_is_error: a failed post command is only reported (default)
--post_cmd_expose_password: put the archive password in the environment and json given to post commands
--no_post_cmd_expose_password: keep the archive password out of them (default)
--nzb_upload_url : upload the nzb to this URL (ftp, http or https)
--nzb_upload_timeout: seconds before a stuck nzb upload is given up (0: no limit)
--post_history : legacy csv history file, one line appended per post
// for compression and par2 support
--tmp_dir : temporary folder where the compressed files and par2 will be stored
--rar_path : RAR absolute file path (external application)
--rar_size : size in MB of the RAR volumes (0 by default meaning NO split)
--rar_max : maximum number of archive volumes
--par2_pct : par2 redundancy percentage (0 by default meaning NO par2 generation)
--par2_path : par2 absolute file path
--pack : Pack posts using config PACK definition (subset of COMPRESS, GEN_NAME, GEN_PASS, GEN_PAR2)
--auto_compress : alias of --pack: enable auto-packing using the config PACK definition
--compress : compress inputs using RAR or 7z
--gen_par2 : generate par2 (to be used with --compress)
--rar_name : provide the RAR file name (to be used with --compress)
--rar_pass : provide the RAR password (to be used with --compress)
--gen_name : generate random RAR name (to be used with --compress)
--gen_pass : generate random RAR password (to be used with --compress)
--length_name : length of the random RAR name (to be used with --gen_name), default: 17
--length_pass : length of the random RAR password (to be used with --gen_pass), default: 13
--rar_no_root_folder: Remove root (parent) folder when compressing Folders using RAR
// NFO options
--keep_nfo_extension: Keep the .nfo extension visible when obfuscating file names
--nzb_copy_nfo : Copy the original .nfo file next to the generated nzb
--auto_include_nfo : auto-post: include a sibling .nfo (same name, different extension) in the same post
// VPN overrides (one-shot for this run, not saved to config)
--vpn : Force all NNTP connections through the configured VPN (master switch ON)
--no_vpn : Disable VPN for this run (master switch OFF, per-server useVpn ignored)
--vpn_profile : Select the active VPN profile by name (must exist in config)
// you can provide servers in one string using -S and/or split the parameters for ONE SINGLE server
-S or --server : NNTP server following the format (<user>:<pass>@@@)?<host>:<port>:<nbCons>:(no)?ssl
-h or --host : NNTP server hostname (or IP)
-P or --port : NNTP server port
-s or --ssl : use SSL
-u or --user : NNTP server username
-p or --pass : NNTP server password
-n or --connection : number of NNTP connections
Examples:
- with VPN override: ngPost-v5.5-x86_64.AppImage -i /data/myPost --pack --vpn --vpn_profile Mullvad-NL
- with monitoring: ngPost-v5.5-x86_64.AppImage --monitor /data/folder1 --auto_compress --rm_posted --disp_progress files
- with auto post: ngPost-v5.5-x86_64.AppImage --auto /data/folder1 --compress --gen_par2 --gen_name --gen_pass --rar_size 42 --disp_progress files
- with NFO options: ngPost-v5.5-x86_64.AppImage -i /data/myPost --auto_compress --keep_nfo_extension --nzb_copy_nfo
- list history as JSON: ngPost-v5.5-x86_64.AppImage --history --json
- resume a failed post: ngPost-v5.5-x86_64.AppImage --resume_post 42
Since v5.4.0, ngPost records every post in a structured SQLite database (replacing the
old CSV POST_HISTORY file, which can still be imported with --history_import_csv). The
database tracks each post down to the individual article, which makes it possible to inspect
the history, regenerate an NZB, or resume a partial/failed post directly from the command line.
By default the database lives next to the configuration:
| Platform | Default path |
|---|---|
| Linux | ~/.config/ngPost/ngPost_history.sqlite |
| Windows | %LOCALAPPDATA%\ngPost\ngPost_history.sqlite |
| macOS | ~/Library/Application Support/ngPost/ngPost_history.sqlite |
Use --post_db <file> (or the POST_DB config keyword) to point to another database.
Note: every option accepts both the underscore and dash form, e.g.
--history_showor--history-show.
# list all posts (TSV columns: id, status, created, name, groups, password)
ngPost --history
# same list as compact JSON for scripting
ngPost --history --json
# full details of one post (files, nzb path, archive name, article counts)
ngPost --history_show 42
ngPost --history_show 42 --include_password # reveal the stored archive passwordThe JSON objects returned by --history expose: id, name, status, groups,
created_at, has_password and password_stored. This pairs nicely with jq:
# names of every completed post
ngPost --history --json | jq -r '.[] | select(.status=="done") | .name'Because it is plain SQLite, you can also query the database directly:
sqlite3 ~/.config/ngPost/ngPost_history.sqlite \
"SELECT id, status, created_at, nzb_name FROM posts ORDER BY id DESC LIMIT 20;"ngPost --regenerate_nzb 42 -o /path/to/output.nzb
ngPost --regenerate_nzb 42 -o output.nzb --include_passwordFrom version 5.5 on.
The record sheet of a post already in the history, from a model you provide.
# into a file
ngPost --export_post_info 42 --post_info_template my_sheet.txt -o sheet.txt
# to stdout, so it can be piped: only the sheet goes there
ngPost --export_post_info 42 --post_info_template my_sheet.txtFor a post made before this feature existed, the par2 percentage, the source name and your own metadata come out empty, and ngPost says so on stderr.
The same model is used automatically after each post when POST_INFO_TEMPLATE
is set. Your fields are given with --post_meta "name=value" or
-m "name=value": both are written in the sheet, and -m publishes the field
in the nzb header on top of that. See Post info files.
When a post is interrupted (network loss, crash, …), the articles that never reached the server are flagged and can be re-posted with a fresh Message-ID — no need to re-upload the whole archive.
ngPost --resume_list # show resumable / partial posts (add --json)
ngPost --resume_check 42 # show the resume status of one post
ngPost --resume_post 42 # resume one post
ngPost --resume_post 42,43,57 # resume several posts (coma separated)
ngPost --resume_all # resume everything that is resumable
ngPost --resume_post 42 --dry_run # show what would be re-posted, without postingngPost --resume_abandon 42 --yes # mark an incomplete post as abandoned
ngPost --resume_purge 42 --yes # drop the technical resume data of a postngPost --history_import_csv /path/to/POST_HISTORY.csvThe original CSV file is preserved; ngPost also imports it automatically on first launch.
From version 5.5 on.
Everything the configuration file can say about post info files, post commands and the nzb upload is also a command line option, so ngPost can be driven from a script or a container with no ngPost.conf at all. What is given on the command line always wins over the configuration file.
| Option | What it does |
|---|---|
--post_info_template <file> |
model used to write the post info file |
--post_info_output <pattern> |
where to write it, variables allowed |
--post_info_only_on_success / --no_post_info_only_on_success
|
write the sheet only for a fully successful post (the default), or always |
--nzb_post_cmd <command> |
command to run after each post, repeatable. It replaces the NZB_POST_CMD lines of the configuration file rather than adding to them |
--post_cmd_timeout <seconds> |
kill a stuck post command (0: no limit) |
--post_cmd_fail_is_error / --no_post_cmd_fail_is_error
|
a failed post command makes ngPost exit non zero, or is only reported (the default) |
--post_cmd_expose_password / --no_post_cmd_expose_password
|
put the archive password in the environment and json given to post commands, or keep it out (the default) |
--nzb_upload_url <url> |
upload the nzb (ftp, http or https only) |
--nzb_upload_timeout <seconds> |
give up on a stuck upload (0: no limit) |
--post_history <file> |
legacy csv history, one line appended per post |
Each boolean comes as a pair so a value set in the configuration file can be turned around for a single run, the same way --vpn and --no_vpn work.
Since v5.4.0, the default configuration file moved from the old legacy location to a per-user application configuration directory:
| Platform | New default config path | Legacy path |
|---|---|---|
| Linux |
$XDG_CONFIG_HOME/ngPost/ngPost.conf or ~/.config/ngPost/ngPost.conf
|
~/.ngPost |
| Windows | %LOCALAPPDATA%\ngPost\ngPost.conf |
ngPost.conf next to the executable |
| macOS | ~/Library/Application Support/ngPost/ngPost.conf |
~/.ngPost |
On first launch, if a legacy configuration exists and the new file does not, ngPost copies the legacy file to the new location and keeps the original file in place. This keeps older ngPost versions usable while allowing v5.4+ to use the new layout.
The same configuration directory is also used for related per-user data, including VPN profile files and the default structured history database ngPost_history.sqlite.
From version 5.5, the final directory name is pinned to ngPost and no longer
follows the executable/AppImage name. A normal first start can adopt an older
name-derived folder without overwriting anything. Configuration assets are
copied; SQLite/WAL files remain at their old path and the adopted POST_DB
continues to select them. Completed decisions are recorded once. Failed
adoptions stop safely and can be retried.
--help, --version and invalid syntax perform no folder creation or
adoption. An explicit -c also bypasses adoption and keeps relative models and
VPN profiles anchored to that configuration file. See
Configuration for the
complete safety and selection rules.
One thing to know before pinning a script to the old file: it has no
POST_DB line, so it would record its posts in a different database from the
one the adopted configuration uses. ngPost says so on every such run, and
Configuration
gives the two ways to keep a single history.
You can still override the configuration file explicitly with:
ngPost -c /path/to/ngPost.conf