ID4i CLI

ID4i provides globally unique IDs for single workpieces and a platform to manage, and exchange data bound to IDs in an inter-organizational manner. For details, please refer to http://id4i.de.

You can use the ID4i command line interface to …​

• …​ perform manual tasks in ID4i

• …​ include ID4i tasks in arbitrary shell scripts

• …​ query ID4i manually or as part of existing workflows.

For detailed documentation of ID4i see http://backend.id4i.de/docs/reference/en/reference.html#_tutorials

🔥	ID4i CLI is currently a work in progress and should not be used in production; at least not without getting in touch first. More operations will be added in the future.

ID4i CLI is configurable using environment variables, a variety of configuration files and command line switches. See the Usage section or id4i help for details.

Since we do not have extensive experience in golang, we are thankful for contributions and/or bitching and nagging, especially in combination with pointers to more idiomatic alternative implementations.

Table of Contents

• Usage
  • Prerequisites
  • Help
• Development
  • Prerequisites
  • Adding new commands
  • Updating the API version
  • Build
  • Run
  • Test

Usage

Prerequisites

For the CLI to be able to communicate with ID4i, you need an ID4i API key.

Complete the following steps to get from zero to your first successful ID4i CLI operation:

1. If you have not already done, register a user on ID4i. Use Sandbox for care-free experimenting, and Production for production use.

2. Create and activate an API key (the development manual has more info and screenshots)

   1. Navigate to API Keys → New API Key

   2. Note your API key secret and your API key ID

   3. Activate the API key

3. Figure out your organization’s namespace (or even better, create a new one) on Organizations

4. Configure the CLI to use your API key

   1. EITHER set ID4I_APIKEY, ID4I_SECRET, ID4I_BACKEND and ID4I_ORGANZATION environment variables

   2. OR use a configuration file in the current or your home directory named .id4i.properties (or .json or .yml) and set the properties apikey, secret, backend and organization there

   3. OR use command line flags for these parameters as described in Help

   4. OR any combination of the above. You get the point.

5. Give your API key the corresponding permissions required to carry out the task you want. Go to the details page of your API key and set the permissions. You can learn about what happens in the background in the development manual.

You can either get a binary for your platform or run the ID4i CLI within Docker: docker run bluerainsoftware/id4i <args>. e.g. docker run bluerainsoftware/id4i help or docker run bluerainsoftware/id4i info -h.

For details on how to configure the image with your API key and other required properties, see https://hub.docker.com/r/bluerainsoftware/id4i-cli/

Help

Main Command

ID4i API commandline application.

Configuration:
  You can set global parameters in different locations (ordered by precedence):
  - As command line parameter, e.g. --apikey or -k
  - Using environment variable under the "ID4I_" prefix, e.g. "ID4I_APIKEY"
  - In a configuration file.
    Default locations are ./.idi.<type> and ~/.id4i.<type> with <type> denoting the file format (json, yml, toml, hcl, properties)
    You can specify a different file using the --config/-c parameter.

  Refer to "id4i help" for available configuration parameters.

Usage:
  id4i [command]

Available Commands:
  collections Operations on labelled, logistic and routing collections
  guids       GUID operations
  help        Help about any command
  history     History operations
  info        Configuration and backend API information
  storage     Storage operations
  transfer    Send/receive GUIDs and Collections to/from other companies

Flags:
      --apikey string         ID4i API key to use
      --backend string        ID4i Backend to use, e.g. sandbox.id4i.de (default "sandbox.id4i.de")
      --config string         config file (default is ./.id4i, falls back to $HOME/.id4i)
  -h, --help                  help for id4i
  -n, --limit int32           Limit result list to <n> items (for operations returning lists) (default 10)
  -o, --offset int32          Result list offset (for operations returning lists)
      --organization string   ID4i organization namespace to work in
      --secret string         API key secret

Use "id4i [command] --help" for more information about a command.

Collections

Operations on labelled, logistic and routing collections

Usage:
  id4i collections [flags]
  id4i collections [command]

Available Commands:
  create      Create a new collection
  delete      Delete collection specified by its ID
  elements    Retrieve elements (contained GUIDs) of the collection identified by --id
  info        Retrieve header data of the collection identified by --id

Flags:
  -h, --help        help for collections
  -i, --id string   ID4i ID of Collection to operate on

Global Flags:
      --apikey string         ID4i API key to use
      --backend string        ID4i Backend to use, e.g. sandbox.id4i.de (default "sandbox.id4i.de")
      --config string         config file (default is ./.id4i, falls back to $HOME/.id4i)
  -n, --limit int32           Limit result list to <n> items (for operations returning lists) (default 10)
  -o, --offset int32          Result list offset (for operations returning lists)
      --organization string   ID4i organization namespace to work in
      --secret string         API key secret

Use "id4i collections [command] --help" for more information about a command.

GUIDs

GUID operations

Usage:
  id4i guids [flags]
  id4i guids [command]

Available Commands:
  create      Create GUIDs

Flags:
  -h, --help   help for guids

Global Flags:
      --apikey string         ID4i API key to use
      --backend string        ID4i Backend to use, e.g. sandbox.id4i.de (default "sandbox.id4i.de")
      --config string         config file (default is ./.id4i, falls back to $HOME/.id4i)
  -n, --limit int32           Limit result list to <n> items (for operations returning lists) (default 10)
  -o, --offset int32          Result list offset (for operations returning lists)
      --organization string   ID4i organization namespace to work in
      --secret string         API key secret

Use "id4i guids [command] --help" for more information about a command.

Transfer

Send/receive GUIDs and Collections to/from other companies

Usage:
  id4i transfer [flags]
  id4i transfer [command]

Available Commands:
  receive     Receive an ID transfer
  send        Prepare the transfer of an ID to another organization
  status      Check the status of an ongoing transfer

Flags:
  -h, --help        help for transfer
  -i, --id string   ID4i ID (GUID or Collection) to operate on

Global Flags:
      --apikey string         ID4i API key to use
      --backend string        ID4i Backend to use, e.g. sandbox.id4i.de (default "sandbox.id4i.de")
      --config string         config file (default is ./.id4i, falls back to $HOME/.id4i)
  -n, --limit int32           Limit result list to <n> items (for operations returning lists) (default 10)
  -o, --offset int32          Result list offset (for operations returning lists)
      --organization string   ID4i organization namespace to work in
      --secret string         API key secret

Use "id4i transfer [command] --help" for more information about a command.

Storage

Storage operations

Usage:
  id4i storage [flags]
  id4i storage [command]

Available Commands:
  upload      Upload new document

Flags:
  -h, --help        help for storage
  -i, --id string   ID4i ID (GUID or Collection) to operate on

Global Flags:
      --apikey string         ID4i API key to use
      --backend string        ID4i Backend to use, e.g. sandbox.id4i.de (default "sandbox.id4i.de")
      --config string         config file (default is ./.id4i, falls back to $HOME/.id4i)
  -n, --limit int32           Limit result list to <n> items (for operations returning lists) (default 10)
  -o, --offset int32          Result list offset (for operations returning lists)
      --organization string   ID4i organization namespace to work in
      --secret string         API key secret

Use "id4i storage [command] --help" for more information about a command.

History

History operations

Usage:
  id4i history [flags]
  id4i history [command]

Available Commands:
  add            Add history item
  list           List ID history
  set-visibility Update history item visibillity

Flags:
  -h, --help        help for history
  -i, --id string   ID4i ID (GUID or Collection) to operate on

Global Flags:
      --apikey string         ID4i API key to use
      --backend string        ID4i Backend to use, e.g. sandbox.id4i.de (default "sandbox.id4i.de")
      --config string         config file (default is ./.id4i, falls back to $HOME/.id4i)
  -n, --limit int32           Limit result list to <n> items (for operations returning lists) (default 10)
  -o, --offset int32          Result list offset (for operations returning lists)
      --organization string   ID4i organization namespace to work in
      --secret string         API key secret

Use "id4i history [command] --help" for more information about a command.

(statically generated using update-readme.sh)

Development

If you need additional commands, feel free to jump in or let us know.

If you want to get involved, we classified some tasks as good first issues to get you started.

Prerequisites

• Go 1.11.2

• Go Dep, get it w/ go get -u -v github.com/golang/dep/cmd/dep

• Docker, if you want to build the docker image. v18.06.1-ce and v17.03.0-ce are known to work

• If you want to scaffold new commands, the cobra generator will help you: go get github.com/spf13/cobra/cobra

• If you want to run the tests, you’ll need jq: https://stedolan.github.io/

Adding new commands

We use the awesome cobra ^[1] and viper ^[2] libraries.

To scaffold a new command, clone the repo and say cobra add <my command> -p rootCmd.

Open the generated command and implement your operation:

• Define your parameters in init.

• Validate your input, if required.

• Use the operations exposed in ID4i (from rootCmd) to call the backend.

• Use the OutputResult and DieOnError functions from rootCmd to report the result of your command.

• Add your command to ./update-readme.sh so the README gets updated with the new command

You can find examples for each step in the existing commands.

If you want to debug the calls you are making, set the DEBUG environment variable to a non-empty value. This will cause the HTTP calls to be logged to the console.

ℹ️	Please don’t forget to add tests for your new commands, see Test

Updating the API version

The API client is generated using go-swagger ^[3].

To update the client for the CLI, run ./generate-api-client.sh -c -d from the project root. Note that -d installs go-swagger locally and -c pulls the current API specification from ID4i production ^[4]

Run the tests and make required corrections in the existing commands if applicable. The ID4i change logs ^[5] are probably helpful.

Build

• git clone git@github.com:BlueRainSoftware/id4i-cli.git $GOPATH/src/github.com/BlueRainSoftware/id4i-cli

• cd $GOPATH/src/github.com/BlueRainSoftware/id4i-cli

• dep ensure -v

• go build -o id4i main.go

• Update the README with the current help contents: ./update-readme.sh

Docker

To build the docker image, run docker build . -t id4i:<my tag>.

The README shown on DockerHub is the README.md file in this repository.

CI

CI Builds live on CircleCI, defined in .circleci/config.yml. Note that currently, the build artifacts (binary and docker image) are not stored anywhere, so you probably need to build it yourself. This will change, promise.

The docker image is built/pushed using the automatic builds on docker hub. The master branch is tagged latest, the develop branch develop. Tags starting with v are used as releases using the tag as version for the image.

Run

After building, you can run the binary w/ ./id4i.

Test

Integration tests live in test/tests. The preflight.sh script creates a user, saves the required information for id4i configuration to a temporary file and creates an id4i configuration file. It can also be used to download the testing framework (bats ^[6]) and to build the binary.

$ ./run-tests.sh -h
Run ID4i CLI tests
Usage: run-tests.sh [-h] [-v] [-i] [-p] [-c] [-b] [-t]
  -h	help - Show this help message.
  -v	version - Show version information.
  -i	install - Install Prerequisites
  -p	preflight - Run preflight script (provision ID4i test user)
  -c	cleanup - Clean up test results after successful tests
  -b	build - Build ID4i binary before testing (requires Go)
  -t	tap-format - Use TAP format test output (for CI reports)

ℹ️	The tests always run against id4i-develop as of now.

---

1. https://github.com/spf13/cobra

2. https://github.com/spf13/viper

3. https://github.com/go-swagger/go-swagger, https://goswagger.io/

4. https://backend.id4i.de/docs/swagger.json; use the corresponding URL for other environments, e.g. https://sandbox.id4i.de/docs/swagger.json

5. https://github.com/BlueRainSoftware/support/tree/master/changelog

6. https://github.com/sstephenson/bats