Command Line Interface (CLI)

The smart.finder CLI is a tool to manage indexing jobs via the command line.

Usage

 $ finderctl <Command> [Options]

Overview of commands

smart.finder CLI provides the following commands:

  • generate-token: generation of a token for login

  • login: authentication with session cookie

  • logout: termination of a session

  • jobs get: Download indexing jobs

  • jobs put: Modify indexing jobs

  • jobs query: Query indexing jobs

  • help: Display help

Global options

-v, --version

The version of the finderctl tool.

-h, --help

Prints information for using a command, finderctl <command> --help, or for the tool itself, finderctl --help.

Example:

 $ finderctl login -h

Get help

To get quick help on a particular command, type the command followed by the -h option:

$ finderctl jobs -h

Commands

generate-token

Generates an authentication token for smart.finder server with INTEGRATED authentication mode. For ONLY_AUTHN please use login and logout.

Enter your name and password when prompted on the command line. You will then receive a new token.

You can use this token to authenticate against the server for both read and write requests. To do this, append the generated token to commands that require authentication using the -t <your-token> parameter.

The token created with this command contains your username and password in Base64 encoded form. This data can be read out of the token very easily. The token is valid as long as your username and password. Therefore, keep the token secret and store it safely.

For security reasons, we recommend using ONLY_AUTHN as the authentication method whenever possible.

Usage

 $ finderctl generate-token

Example

$ finderctl generate-token
Generate an authentication token for managing indexing jobs.

✔ Username: · admin
✔ Password: ·

Your authentication token is:
YWRtaW46YWRtaW4=

login

Logs you into smart.finder if smart.finder server is configured with ONLY_AUTHN authentication mode. If smart.finder server is configured with INTEGRATED mode, use generate-token instead.

On the command line, enter your name and password when prompted.

With this command, the CLI receives a session cookie from the server. All subsequent commands automatically use this cookie for authentication, so no new authentication is required for the duration of the session.

Usage

 $ finderctl login [options]

Example

$ finderctl login -u https://mysmartfinder-url.de

Please enter your credentials to login to smart.finder.
? Username: admin
? Password: [hidden]

Options

-c, --configfile <configfile>

Path to a JSON configuration file

In this configuration file parameters for this and other commands can be preset.

-u, --auth-url <auth-url>

URL for authentication

The URL to smart.finder or to map.apps where the smart.finder bundles are installed to request a session cookie. If this parameter is not specified in the command line, you will be prompted for this URL during the execution of the login command.

logout

Ends the session that was started with the login command.

The command deletes the session cookie from local memory. If you also specify a URL using -u, you will also be logged out of the server. Otherwise, the server-side session persists until it expires on its own.

Usage

$ finderctl logout [options]

Example

$ finderctl logout -u https://mysmartfinder-url.de
Successfully logged out from 'https://mysmartfinder-url.de'.

Options

-c, --configfile <configfile>

Path to a JSON configuration file

In this configuration file parameters for this and other commands can be preset.

-u, --auth-url <auth-url>

URL for authentication/logout

The URL to smart.finder or map.apps (where the smart.finder bundles are installed) to terminate the server-side session. If not specified, only the temporary login files on your machine will be deleted. The server-side session will remain until it expires on its own.

jobs

Use the jobs command to interact with the jobs managed in smart.finder. Following subcommands are avialable:

get and put

The two subcommands get and put allow the jobs to be downloaded or uploaded between the smart.finder server and a local directory. With jobs get the indexing jobs can be retrieved as JSON file from the server and saved locally. jobs put creates or updates existing indexing jobs on the server using the local JSON file.

Usage
$ finderctl jobs {get|put} [options]
Example
$ finderctl jobs get -t YWRtaW46YWRtaW4= -u http://smartfinder.conterra.de/server -d c:/temp/jobs (1)
$ finderctl jobs get -u http://smartfinder.conterra.de/server -d c:/temp/jobs -q coreName:core0 (2)
$ finderctl jobs get -u http://smartfinder.conterra.de/server -d c:/temp/jobs -f title,timestamp (3)
$ finderctl jobs put -u http://smartfinder.conterra.de/server -d c:/temp/jobs (4)
1 Query jobs, smart.finder Server with INTEGRATED security mode
2 Query jobs for index core0
3 Query jobs with specific fields only
4 create/update jobs
Options
-u, --url <url>

URL to the smart.finder server interface

The URL is identical to the URL entered for the finder.service.url configuration property in the smart.finder application.properties file.

-d, --directory <directory>

Local directory of the JSON file with jobs

Always use the slash as a separator in the directory path.

-c, --configfile <configfile>

Path to a JSON configuration file

In this configuration file parameters for this and other commands can be preset.

-q, --query <query>

Query expression to filter the jobs

To get possible expressions use the jobs query command.

Format: field1:value1,field2:value2.

-f, --fields <fields>

Fields to be queried for each job

If not specified, all fields will be included.

-t, --token <token>

The authentication token for queries against a smart.finder server with INTEGRATED security mode.

query

The query subcommand allows you to query information about the jobs. You can also use this information for the query options of the individual commands.

Usage
$ finderctl jobs query [options]
Example
Information about jobs filtered by inactive state
$ finderctl jobs query -s inactive -u http://localhost:8080/ct-finder-server-webapp-2.0.9
1 inactive job found.
{ id: 'AEaLrhyj2UhxO2mh', title: 'Demoportal CSW', state: 'inactive' }
Information about jobs filtered by id
$ finderctl jobs query -id AEaLrhyj2UhxO2mh -u http://localhost:8080/ct-finder-server-webapp-2.0.9
{ id: 'AEaLrhyj2UhxO2mh', title: 'Demoportal CSW', state: 'inactive' }
Detailed information about jobs
$ finderctl jobs query -id AEaLrhyj2UhxO2mh -d -u http://localhost:8080/ct-finder-server-webapp-2.0.9
{
id: 'AEaLrhyj2UhxO2mh',
count: '70',
source: 'https://demos.conterra.de/ct-smartfinder-csw-1.0.3/api',
title: 'Demoportal CSW',
creator: 'admin',
email: '',
created: '2021-08-02T15:19:39Z',
modified: '2021-08-03T13:14:50Z',
state: 'inactive',
cronstring: '',
context: '{"type":"csw","version":"2.0.2"}',
lastSuccess: '2021-08-03T11:14:20.543Z',
lastExecutionResult: 'success',
executionCount: 2,
targetState: 'inactive',
coreName: 'core0',
_version_: '1707070497780400128',
timestamp: '2021-08-03T11:14:50.010Z'
}
Options
-s, --state <state>

Filters jobs by their state

Allowed values: scheduled, pending, inactive, executing.

-t, --token <token>

The authentication token for queries against a smart.finder server with INTEGRATED security mode.

-d, --detail

Display of the detailed information

Without this option, only the ID, title and status of the jobs will be printed.

-id, --identifier <id>

Filters the jobs according to their ID

-c, --configfile <path to configuration file>

Path to a JSON configuration file

In this configuration file parameters for this and other commands can be preset.

-u, --url <url>

URL to the smart.finder server interface

The URL is identical to the URL entered for the finder.service.url configuration property in the smart.finder application.properties file.

Using a configuration file

For most commands you can use a configuration file to save settings. Especially for frequently used properties you can avoid entering the same values again and again. Instead, you specify the configuration file using the -c option in the command line and optionally add any missing settings.

In addition, security-relevant information such as a token or password is better protected this way. It is not directly visible during execution and does not appear in the command line history.

Structure

In the configuration file in JSON format, an object with the corresponding options is listed for each command. Subcommands, for example the get subcommand of the jobs command, are specified in the configuration file as subobjects of the parent command.

{
  "commandA": {
    "subCommand": {
      "option": "value"
    }
  },
  "commandB":{
    "option": "value"
  }
}

A central specification of multiple used options, like token, is not possible. These can differ in values among the various commands due to different server instances.

Spelling of parameter names

In the file the written out parameter names must be used. The abbreviations mostly used in the command line are not supported. Therefore use examples directory instead of -d.

The spelling of the parameters can be queried using the help function on the command line. Example for the jobs put command:

$ finderctl jobs put -h
Usage: finderctl jobs put [options]

Create/update indexing jobs from local files.

Options:
  -c, --configfile <configfile>  Path to a JSON configuration file.
  -t, --token <token>            Optional. Base64-encoded token for HTTP Basic
                                 authentication.
  -u, --url <url>                URL to the smart.finder server endpoint.
  -d, --directory <directory>    Path to the directory where the indexing job files
                                 are located.
  -q, --query <query>            A query expression to filter the jobs. Format:
                                 field1:value1,field2:value2
  -f, --fields <fields>          The fields of a job to include. If not specified,
                                 all fields are considered.
  -h, --help                     display help for command

You can use the parameter names that start with two hyphens like --directory in the configuration file without the leading hyphens.

Hyphenated parameter names like --auth-url are used in the configuration file in camelCase notation. Thus --auth-url becomes authUrl.

Additional options for login command

For the login command, you can specify the name and password for login in addition to the above command options. For security reasons, you can only use these in the configuration file, not on the command line.

username

The login name to the server.

password

The password for logging in.

Example

The following is an example of a configuration file.

{
  "login": {
    "authUrl": "https://smartfinder.conterra.de", (1)
    "username": "admin" (2)
  },
  "jobs": { (3)
    "get": {
      "url": "https://smartfinder.conterra.de/server",
      "directory": "c:/temp/smartfinder"
    },
    "put": { (4)
      "directory": "c:/temp/smartfinder"
    }
  }
}
1 --auth-url becomes authUrl
2 username is a parameter exclusive for use in configuration files
3 jobs consists of the get and pull subcommands, these must be specified as objects within jobs
4 since only the directory is defined here, but not the url, this must be specified when executing on the command line