CLI

Remote server must respond to plain-text health check ping

req~jabref.remote.health-check~1

The remote listener accepts the versioned plain-text request JABREF/1 PING and responds with JABREF/1 PONG jabref. This check identifies a running JabRef instance without requiring clients to implement the Java serialization protocol. Existing serialized remote-operation requests remain supported.

Needs: impl

JabKit commands must accept input file as positional argument

req~jabkit.cli.input-flag~2

All jabkit commands that need a file input must accept it as a positional FILE argument. For backward compatibility, the --input option is also accepted as an alias. Exactly one of the two forms must be supplied. See ADR 57 for more details.

Needs: impl

JabKit input argument must accept HTTP, HTTPS, and FTP URLs

req~jabkit.cli.input-url~2

The positional FILE argument and its --input alias additionally accept an http://, https://, or ftp:// URL. This holds for every input a jabkit command reads, including each argument of a command taking several of them. The URL is downloaded to a local temporary file before use; a download failure is reported as a regular CLI error (exit code SOFTWARE) rather than a “file not found” usage error. For a command reading several inputs, an unusable input is skipped and the remaining ones are still processed, with the command exiting non-zero afterwards. See ADR 65 for more details.

Needs: impl

JabKit input argument must accept shared database URLs

req~jabkit.cli.input-shared-db~1

The positional FILE argument and its --input alias additionally accept a PostgreSQL connection URL (for example postgresql://user:secret@host:5432/library) pointing at a JabRef shared library. The library is exported to a local temporary file before use; the access is read-only, nothing is written back to the database. A database that is not a JabRef shared library, and any connection failure, is reported as a regular CLI error (exit code SOFTWARE). See ADR 74 for more details.

Needs: impl

JabKit must display banner only when help is requested

req~jabkit.cli.banner-shown~1

The banner for the CLI (“JabKit”) is only shown if the help is output, meaning when no command is given (falling back to help) or when --help is explicitly requested.

Rationale: Suppressing decorative banners during normal command invocations prevents noise in automated scripts and increases accessibility (source: Accessibility of Command Line Interfaces).

Needs: impl

JabKit check commands must emit findings in machine-readable format

req~jabkit.cli.check-errorformat-output~1

The jabkit check subcommands emit their findings in a line-oriented file:line:column:citationKey[:field]: message format, suitable for editors and CI tooling.

Entry-level findings (for example, on the citation key itself) carry only the citation key. Field-level findings additionally carry the affected field name.

Needs: impl

JabKit convert command must write pure converted data to standard output

req~jabkit.cli.convert-stdout-format~1

When jabkit convert writes to standard output, it uses the exporter selected by --output-format. Progress messages are written to standard error so standard output contains only the exported data.

Needs: impl

JabKit check commands must support GitHub Actions output format

req~jabkit.cli.check-github-actions-output~1

The jabkit check subcommands support an additional github-actions output format that emits each finding as a GitHub Actions workflow command of the shape ::error file=<file>,line=<line>,col=<col>,title=<title>::<message>.

The file, line, col, and title property values are URL-encoded so that Windows-style paths (containing :) and titles (containing : between citation key and field name) are parsed correctly by the GitHub Actions runner.

Needs: impl