@teipublisher/jinks-cli

A command-line interface tool for managing TEI Publisher applications with Jinks.

Installation

npm install -g @teipublisher/jinks-cli

Usage

After installation, you can use the jinks command from anywhere in your terminal.

General Options

jinks -h or jinks --help

Display help information for the jinks CLI tool or for a specific command.

jinks -h
jinks create --help

jinks -v or jinks --version

Display the version number of the jinks CLI tool.

jinks -v

Commands

jinks list

List all installed applications on the server.

jinks list

jinks create [abbrev]

Create a new application. If no abbreviation is provided, you'll be prompted to enter one.

jinks create my-app

Options:

• -s, --server <address> - Server address (default: http://localhost:8080/exist/apps/jinks)
• -u, --user <username> - Username (default: tei)
• -p, --password <password> - Password (default: simple)
• -e, --edit - Use text editor rather than interactive mode
• -q, --quiet - Do not print banner
• -c, --config <file> - Use the given configuration file rather than interactive mode to create the application.

jinks edit [abbrev]

Edit an existing application configuration. If no application is provided, you'll be prompted to select from installed applications.

jinks edit my-app

Options:

• -s, --server <address> - Server address
• -u, --user <username> - Username
• -p, --password <password> - Password
• -e, --edit - Use text editor rather than interactive mode
• -q, --quiet - Do not print banner
• -r, --reinstall - Fully reinstall application, overwriting existing files
• -a, --all - Ignore last modified date and check every file for changes

jinks update [abbrev]

Update an existing application. If no application is provided, you'll be prompted to select from installed applications.

jinks update my-app

Options:

• -s, --server <address> - Server address
• -u, --user <username> - Username
• -p, --password <password> - Password
• -q, --quiet - Do not print banner
• -r, --reinstall - Fully reinstall application, overwriting existing files
• -a, --all - Ignore last modified date and check every file for changes
• --sync - Sync updated files to the local directory (also always syncs .jinks.json and context.json)

jinks config [abbrev]

Get configuration for an application.

jinks config my-app

Options:

• -x, --expand - Show the expanded configuration
• -s, --server <address> - Server address
• -u, --user <username> - Username
• -p, --password <password> - Password

jinks run [abbrev] [action]

Run an action on an installed application. If no action is provided, you'll be prompted to select from available actions.

jinks run my-app reindex

Options:

• -U, --update - Perform an update of the application before running the action
• -s, --server <address> - Server address
• -u, --user <username> - Username
• -p, --password <password> - Password

jinks create-profile [abbrev]

Create a new profile (blueprint, feature, or theme) and save it to a directory. If the resulting package is built (with ant) and installed into the database, it will appear within jinks as a profile users can select to extend.

jinks create-profile my-feature

Options:

• -s, --server <address> - Server address
• -u, --user <username> - Username
• -p, --password <password> - Password
• -o, --out <file> - Directory to save the profile configuration to
• -q, --quiet - Do not print banner

jinks edit-profile <dir>

Edit an existing profile configuration.

jinks edit-profile ./my-feature

Options:

• -s, --server <address> - Server address
• -u, --user <username> - Username
• -p, --password <password> - Password
• -q, --quiet - Do not print banner

jinks watch [dir]

Watch a local directory for file changes and automatically synchronize them to the corresponding eXist-db collection. Reads the target collection and credentials from repo.xml in the watched directory.

jinks watch
jinks watch ./my-app

The target collection (/db/apps/<target>) and database credentials are taken from the <target> and <permissions> elements in repo.xml. The -u and -p options override the credentials from repo.xml when needed.

Synchronized events:

| Event | Action | |---|---| | File added or changed | Upload to database | | File deleted | Remove from database | | Directory added | Create collection in database | | Directory deleted | Remove collection from database |

The following paths are never synchronized: .git, build, node_modules, *.xar, .DS_Store.

Options:

• -s, --server <address> - Server address (default: http://localhost:8080/exist/apps/jinks)
• -u, --user <username> - Override the username from repo.xml
• -p, --password <password> - Override the password from repo.xml

Examples

Create a new application interactively

jinks create

Create a new application with specific abbreviation

jinks create my-tei-app

Edit an existing application (with interactive selection)

jinks edit

Edit a specific application

jinks edit my-tei-app

Update an application with force flag

jinks update my-tei-app --all

Update and sync changed files to the local directory

jinks update my-tei-app --sync

Run a reindex action (with interactive action selection)

jinks run my-tei-app

Run a specific action

jinks run my-tei-app reindex

Create a new feature profile

jinks create-profile my-feature --out ./my-feature

Edit an existing profile

jinks edit-profile ./my-feature

Watch the current directory and sync changes to the database

jinks watch

Watch a specific application directory

jinks watch ./my-tei-app

Connect to a different server

jinks list --server http://my-server:8080/exist/apps/jinks

Interactive Features

The CLI provides rich interactive features:

• Application Selection: When no application abbreviation is provided, you'll be presented with a list of installed applications to choose from
• Action Selection: When running actions, you can select from available actions if none is specified
• Profile Selection: Interactive checkboxes for selecting features and dependencies
• Conflict Resolution: Automatic detection and resolution of file conflicts during updates
• Dependency Management: Automatic detection and addition of missing dependencies

Configuration

The CLI connects to a Jinks server running on eXist-db. By default, it connects to:

• Server: http://localhost:8080/exist/apps/jinks
• Username: tei
• Password: simple

You can override these defaults using command-line options.

Profile Types

When creating profiles, you can choose from three types:

• Blueprint: Base configuration for an application
• Feature: Reusable functionality module
• Theme: Styling and appearance configuration

Requirements

• Node.js 20.0.0 or higher
• A running eXist-db instance with Jinks installed

License

GPL-3.0-or-later

Repository

https://github.com/eeditiones/jinks