Logging in

To connect to Arkindex, CLI commands use a configuration file either:

• Managed transparently with the arkindex login command; or
• Provided explicitly with the --gitlab-secure-file parameter.

Login command

Before running any of the Arkindex CLI commands, you need to log into Arkindex.

In your terminal, enter the following command:

arkindex login

You will then be prompted to enter:

• An Arkindex instance URL (arkindex.teklia.com, ee.preprod.arkindex.teklia.com…). If you do not enter anything here, the selected instance will be demo.arkindex.org by default.
• The credentials for your account on this Arkindex instance:
  • Your e-mail address,
  • Your password.

Profiles

Once successfully logged in, you will then be asked to choose a slug to save this authentication profile as. For example, you can save your credentials for ee.preprod.arkindex.teklia.com as preprod. This profile will then be available when you run any CLI commands. If you run:

arkindex -p preprod elements list --parent $ARKINDEX_ELEMENT_ID

Then the CLI will look for the specified element on ee.preprod.arkindex.teklia.com, with the access rights of the account you used to log in.

Default profile

After saving a profile under a slug, you will be asked whether or not you want to set this profile as the default one. The default profile is the one that will be used for running any CLI command if you do not specify another profile using the -p flag. So if you say yes to saving the preprod profile as default, any command you run will target the ee.preprod.arkindex.teklia.com instance, using the credentials provided for this profile.

Once you have saved a profile as the default one, in order to target a different Arkindex instance or to use different credentials you will need to explicitly use a different profile using the -p flag.

Warning

Logging in again using arkindex login does not override the default profile. If you have saved a default profile, and use arkindex login to log into a different instance or to use a different account, any command you run afterwards will use the default profile and not the one you just used to log in, unless:

• You replace the existing default profile with this new one, when asked if you want to save this profile as default; or
• You specify the profile to use with the -p flag. For example, if you have created a new demo profile that target the demo.arkindex.org instance, and you want to keep your preprod profile as the default one, then to list elements on the demo instance you will need to run the command like this:

arkindex -p demo elements list --parent $ARKINDEX_ELEMENT_ID

Use command line arguments

Instead of running the arkindex login command bare and being prompted to enter the Arkindex instance address, e-mail address and password, you can use arguments to specify the Arkindex instance (--host) and e-mail address (--email) directly:

arkindex login --host ee.preprod.arkindex.teklia.com --email $me@mail.com

You will then be prompted to enter the corresponding password.

GitLab Secure File

To avoid having to log in with the arkindex login command, you can use the --gitlab-secure-file parameter for any CLI commands:

arkindex --gitlab-secure-file arkindex-cli.yml elements list --parent $ARKINDEX_ELEMENT_ID

The filename passed as parameter must correspond to a GitLab Secure File which has the following format:

default_host: <profile_slug>
gpg_key: null
hosts:
  <profile_slug>:
    token: xxxxxxxx
    url: https://url.arkindex.org

To retrieve this file, the following environment variables are required:

• CI to know if the command is launched from a GitLab CI (it can contain any value),
• CI_API_V4_URL to know the URL of the GitLab instance where the file is located,
• CI_JOB_TOKEN to authenticate to the GitLab instance,
• CI_PROJECT_ID to know which project the file belongs to.

Profiles

Profiles are listed under the hosts key of the GitLab Secure File. For example, you can have the profile preprod for ee.preprod.arkindex.teklia.com:

hosts:
  preprod:
    token: xxxxxxxx
    url: https://ee.preprod.arkindex.teklia.com

This profile will then be available when you run any CLI commands. If you run:

arkindex --gitlab-secure-file arkindex-cli.yml -p preprod elements list --parent $ARKINDEX_ELEMENT_ID

Then the CLI will look for the specified element on ee.preprod.arkindex.teklia.com, with the access rights of the account you provided in the GitLab Secure File.

Default profile

The default profile is defined by the default_host key of the GitLab Secure File. The default profile is the one that will be used for running any CLI command if you do not specify another profile using the -p flag. So if you have the preprod profile as default:

default_host: preprod
hosts:
  preprod:
    token: xxxxxxxx
    url: https://ee.preprod.arkindex.teklia.com

any command you run will target the ee.preprod.arkindex.teklia.com instance, using the credentials provided for this profile.

Once you have defined a profile as the default one, in order to target a different Arkindex instance or to use different credentials you will need to explicitly use a different profile using the -p flag. For example, if you have a demo profile that target the demo.arkindex.org instance, and you want to keep your preprod profile as the default one:

default_host: preprod
hosts:
  preprod:
    token: xxxxxxxx
    url: https://ee.preprod.arkindex.teklia.com
  demo:
    token: xxxxxxxx
    url: https://demo.arkindex.org

then to list elements on the demo instance you will need to run the command like this:

arkindex --gitlab-secure-file arkindex-cli.yml -p demo elements list --parent $ARKINDEX_ELEMENT_ID