# Designer, command line client, tester and REST server

Guide: [Designer reference](https://docs.ncreport.org/ncreport/2.36/designer/reference.html),
[Command line client](https://docs.ncreport.org/ncreport/2.36/cli/commandline.html),
[NCReport Tester](https://docs.ncreport.org/ncreport/2.36/cli/runner.html).

## NCReport Designer

Executable `NCReportDesigner` (debug build `NCReportDesignerd`), in `<build>/bin` or the package's `bin/`.

```sh
NCReportDesigner reports/invoice.ncr --tr=de
```

- The report file must be the **first** argument. Other options: `--tr=<lang>` (UI language), `--appname=`,
  `--orgname=`, `--print`.
- Saved database connections and settings are stored with `QSettings` (organization `GrassBits`, application
  `NCReportDesigner`): `~/.config/GrassBits/NCReportDesigner.conf` on Linux, the registry on Windows. Passwords are
  stored as plain text or Base64.
- The Designer writes templates with small, stable XML diffs, so templates belong in version control. After editing
  a template by hand, opening and saving it in the Designer normalizes it. A hand-written report-level `<parameters>`
  block is not written back.

When the user wants to change a report's layout, suggest the Designer for visual work and edit the XML for
mechanical changes (renaming a column in every field, changing a query, adding a parameter).

## Command line client

Executable `NCReport` (in `<build>/bin`). It creates a `QApplication`, prints `OK. Runtime: …ms` on success or
`Error: <message>` with exit code 1.

```sh
NCReport -f reports/orders.ncr -o pdf -of orders.pdf \
         -q QPSQL -h localhost -d shop -u report -p secret -c shop \
         -par year,2026 -par region,EU
```

| Option | Meaning |
| --- | --- |
| `-f`, `--report-file <file>` | Template file |
| `-o`, `--output <type>` | `pdf`, `svg`, `html`, `image`, `excel`, `print`, `preview` (default) |
| `-of`, `--output-file <file>` | Output file (default `test.pdf`) |
| `-par <name>,<value>` or `-add-parameter <name>,<value>` | Parameter, repeatable. Single dash: `--add-parameter` does not work although the usage text shows it |
| `-q`, `--sql-driver` | Qt SQL driver, default `QMYSQL` |
| `-h`, `-u`, `-p`, `-pt`, `-d` | Host (default `localhost`), user (default `root`), password, port, database. A connection is opened only when `-d` is given |
| `-c`, `--connection-id` | Connection name the template's `connID` refers to (default `conn`; `default` = the default connection) |
| `-cs`, `--connect-string user/pass@host` | Connection in one argument |
| `-l`, `--language` | Report language for translated labels |
| `-td`, `--template-dir` | Template directory for text output |
| `-hs`, `--htmlstrategy 1\|2` | HTML layout, `-css`, `--css-file` stylesheet |
| `-n`, `--printer`, `--copies`, `--nodialog` | Printing |

`--force-copy`, `-co` (`--connect-option`) and `-dbid` (`--report-db-id`) are accepted but have no effect.
On a Linux server without a display, start it with `-platform offscreen` (or `QT_QPA_PLATFORM=offscreen`); this is
standard Qt behavior, not an NCReport option.

## NCReport Tester

Executable `NCReportRunner`: a small GUI to run a template against a database with parameters and see the result
in each output. Its only argument is a report file. It registers two custom test data sources, `cds0` and `cds2`.
Settings are kept with `QSettings("GrassBits", "NCReportTester")`.

## NCReport REST API Server

A separately licensed, binary-only HTTP service (Linux, Windows) that runs reports from a report directory and returns
PDF. Configured in `etc/webapp1.ini` (port, report directory), started with `./NCReportWeb -e`.

```text
http://localhost:8080/report?reportid=group_demo&productid=512
```

`reportid` is the template file name without its extension; every other query parameter becomes a report
parameter (`$P{productid}`). A failed report answers with a body that starts with `Error`, so check the body, not
only the HTTP status. Product page: https://ncreport.org/rest-api-server/
