NeetoCI CLI Reference

`ncci`, the NeetoCI Command Line Interface (CLI), makes it easy to create and manage your NeetoCI projects and resources directly from the terminal. It’s an essential part of using NeetoCI.

Download and Install

To download and install ncci, copy and paste the installation command:

Installation using curl command (Linux/macOS):

curl https://ncci-cli-releases.s3.amazonaws.com/get.sh | bash

Installation using Homebrew (macOS):

brew install bigbinary/tap/ncci

Next, you'll need to connect ncci to an organization. The command includes the URL and access token. In your web browser, you'll see something similar to:

ncci connect ORGANIZATION.neetoci.com ACCESS_TOKEN

You can find the exact ncci connect command, which includes your current organization's name and access token, by selecting the CLI widget in the top-right corner of any screen on NeetoCI.

Your access token is always available, and revokable, on your My Settings page.

Overview

Syntax

The general syntax of the ncci the utility is as follows:

ncci [COMMAND] [RESOURCE] [NAME] [flags]

where [COMMAND] is the name of the command as explained in this reference page, [RESOURCE] is the resource type that interests us, [NAME] is the actual name of the resource and [flags] are optional command line flags.

Not all ncci commands require a [RESOURCE] value and most ncci commands do

not have [flags].

Operations

The following list briefly describes all ncci operations:

• connect: the connect command is used for connecting to an organization

  for the first time.

• context: the context command is used for switching organizations.

• get: the get command is used for getting a list of items for an existing

  type of resource as well as getting analytic information about specific

  resources.

• debug: the debug command is used for debugging jobs and projects.

• help: the help command is used for getting help about ncci or an

  existing ncci command.

• version: the version command is used to get the version of the ncci

  utility.

Resource types

You can use ncci to manipulate two types of NeetoCI resources: jobs and projects. Resource related operations require either a valid resource name or an ID.

Jobs

A job is the only NeetoCI 1.0 entity that can be executed in a Virtual Machine (VM). You cannot have a pipeline without at least one job.

The jobs of NeetoCI 1.0 pipelines are independent of each other because they run in completely different Virtual Machines.

Projects

A project is the way NeetoCI 1.0 organizes, stores, and processes repositories. As a result, each NeetoCI 1.0 project has a direct relationship with a single repository.

However, the same repository can be assigned to multiple NeetoCI 1.0 projects under different names. Additionally, the same project name can exist within multiple NeetoCI 1.0 organizations, and deleting a N1.0 project from an organization will not automatically delete it from another.

organizations. Last, the related repository will remain intact after deleting a project from NeetoCI 1.0.

You can use the same project name in multiple organizations but you cannot use the same project name more than once within the same organization.

Working with organizations

This group of ncci commands for working with organizations contain the ncci connect and ncci context commands.

ncci connect

The ncci connect command allows you to connect to a NeetoCI 1.0 organization for the first time and requires two command line arguments. The first command line argument is the organization domain and the second command line argument is the user authentication token – this command requires an existing organization.

The ncci connect command checks whether the user entered the correct authentication token or not. If the authentication token is correct, it is stored on the current computer. If the authentication token is incorrect, it is not stored on the current computer.

Organizations are created using the NeetoCI 1.0 web interface.

The authentication token depends on the active user.

Once you connect to an organization, you do not need to execute ncci connect to connect to the organization again. You can connect to any organization that you are already a member of using the ncci context command.

ncci connect example

The ncci connect command should be executed as follows:

ncci connect spinkart.neetoci.com NeUFkim46BCdpqCAyWXN

ncci context

The ncci context command is used for listing which organizations the active NeetoCI 1.0 user belongs to and for changing between organizations.

The ncci context command can be used with or without any command line parameters. If ncci context is used without any other command line parameters, it returns a list of NeetoCI 1.0 organizations the active user has previously connected to the ncci utility. When used with a command line argument, which should be a valid organization name that the active user belongs to,

ncci context will change the active organization to the selected one.

ncci context example

The next command lists all the organizations to which the connected user belongs:

ncci context

In the output of ncci context, the active organization will have a *character in front of it.

If you use an argument with ncci context, then that argument should be a valid organization name as it appears in the output of ncci context. So, in order to change from your current organization to spinkart_neetoci_com, you should execute the following command:

ncci context spinkart_neetoci_com

Working with resources

This group of ncci commands includes the most often used commands ncci get. This command allows you to work with resources.

ncci get

The ncci get command can do two things. First, it can return a list of items for a given resource type that can be found in the active organization. This option requires a command line argument, which is the resource type. Second, it can return analytical information for a given resource. In this case, you should provide ncci get with the type of resource and the name of the resource that interests you, in that exact order.

In the first case, ncci get can be used as follows:

ncci get [RESOURCE]

In the second case, ncci get should be used as follows:

ncci get [RESOURCE] [name]

In the case of a job resource, you should give the Job ID of the job that interests you and not its name.

ncci get examples

As the ncci get command works with resources, you will need to specify a resource type each time you issue a ncci get command.

So, in order to get a list of the available projects for the current user within the active organization, you should execute the following command:

ncci get projects

Working with jobs

The command for working with jobs includes the ncci debug commands.

ncci debug for jobs

The general form of the ncci debug command for jobs is the following:

ncci debug job [Job ID]

This will start a new interactive job based on the specification of an old job, export the same environment variables, inject the same secrets, and connect to the same git commit.

Commands in the debug mode are not executed automatically, instead they are stored in ~/commands.sh. This allows you to execute them step-by-step, and inspect the changes in the environment.

By default, the duration of the SSH session is limited to one hour. To run longer debug sessions, pass the duration flag to the previous command:

ncci debug job [job-id] --duration 30m

A debug session does not include the contents of the repository related to your NeetoCI 1.0 project. Run checkout in the debug session to clone your repository.

The --duration flag

By default, the SSH session of a ncci debug command is limited to one hour. In order to change that, you can pass the --duration flag to the ncci debug command.

You can define the time duration using numeric values in the XXhYYmZZs format in any valid combination. One hour can be defined as 1h0m0s, 1h, or even 60m.

Help commands

The last group of ncci commands includes the ncci help and ncci versioncommands, which are help commands.

ncci help

The ncci help command returns information about an existing command when it is followed by a valid command name. If no command is given as a command line argument to ncci help, a help screen is displayed.

ncci help example

The output of the ncci help command is static and identical to the output of the ncci command when executed without any command line arguments.

Additionally, the help command can be also used as follows (the connectcommand is used as an example here):

ncci connect help

In this case, help will generate information about the use of thencci connect command.

ncci version

The ncci version command requires no additional command line parameters and returns the current version of the ncci tool.

ncci version example

The ncci version command displays the used version of the ncci tool. As an example, if you are using ncci version 1.0.2, the output of ncci versionwill be as follows:

$ ncci version
v1.0.2

Your output might be different.

Additionally, the ncci version command cannot be used with the -f flag and does not create any additional output when used with the -v flag.

Flags

The --help flag

The --help flag, which can also be used as -h, is used for getting information about a ncci command or ncci itself.

The --verbose flag

The --verbose flag, which can also be used as -v, displays verbose output – you will see the interaction and the data exchanged between ncci and the NeetoCI 1.0 API.

This flag is useful for debugging.

Command aliases

The words of each line that follows, which represent resource types, are equivalent:

- project, projects, and prj

- job and jobs

As an example, the following three commands are equivalent and will return the same output:

ncci get project
ncci get prj
ncci get projects