Instacli

Instantly create CLI applications with light scripting in Yaml!

Use Instacli to quickly automate or prototype light tasks like testing out APIs. Sprinkle in some user interaction.

As-code, but without the complexity of actual code.

Full Example

Get a flavor of Instacli with this example file greetings.cli:

Script info:
  description: Multi-language greeting

Input parameters:
  name: Your name
  language:
    description: Select a language
    enum:
      - English
      - Spanish
      - Dutch

POST:
  url: http://localhost:2525/greeting
  body:
    name: ${input.name}
    language: ${input.language}

Print: ${output}

Run the script with this command:

cli greetings.cli

When running it, we get prompted for input before a POST request is made to the server. The greeting that we get back is printed.

? Your name Hes
? Select a language 
 ❯ ◉ English
   ◯ Spanish
   ◯ Dutch

Hi Hes!

You can specify the parameters as arguments. Find out what to pass with the --help option:

cli --help greetings.cli

Will print:

Multi-language greeting

Options:
  --name       Your name
  --language   Select a language

We can call the example again with the parameters filled in:

cli greetings.cli --name Hes --language Spanish

And we get the result in Spanish:

¡Hola Hes!

Documentation

All of Instacli is defined in the instacli-spec.

• CLI defines the cli shell command
• Language defines the structure of the Instacli scripting language
• Command reference defines all commands with descriptions, code examples and tests.

Build & Run

The Instacli implementation is in Kotlin.

Build it

• Install a current JDK

./gradlew build
alias cli="java -jar `pwd`/build/libs/instacli-*.jar"

Run it

Run the "Hello world" example:

cli samples/hello.cli

See Running instacli files for more information on the cli command.

Explore

There are more examples in the samples directory - check them out!

Explore them all with the command:

cli samples

The following example will provide an interactive experience and connect to the Spotify API:

cli samples/spotify

When connecting to Spotify for the first time, the script will ask you for your login credentials (App Client ID and Client secret -- you should already have those). These will be stored in ~/.instacli/credentials.yaml and will be used for subsequent invocations.

Highlight Reel

Instacli has two main ideas:

1. Everything is Yaml.
2. Keep it simple.

Hello world

This is the simplest Instacli progam, hello.cli:

Print: Hello from Instacli!

Invoke it with

cli hello.cli

And it will print the expected message:

Hello from Instacli!

HTTP requests as code

Tired of remembering the exact curl syntax or forgetting which tab had that request that worked in Postman?

Simply write your GET request as-code with Instacli:

GET: http://localhost:2525/greetings

Here's a POST:

POST:
  url: http://localhost:2525
  path: /greeting
  body:
    name: Hes
    language: Dutch

Define input

Define all command-line options in Yaml. Take this file simple-options.cli

Script info:
  description: Call Acme

Input parameters:
  user: Username
  language: Preferred language

This will automatically generate a command description and command line options:

cli --help simple-options.cli

Call Acme

Options:
  --user       Username
  --language   Preferred language

Input options

Instacli allows you to specify the type and format of input properties. Here's an example file input-options.cli

Script info:
  description: Different input options

Input parameters:
  user:
    description: Username
    short option: u
  password:
    description: Password
    secret: true
    short option: p

cli --help input-options.cli

Different input options

Options:
  --user, -u   Username
  --password, -p   Password

Interactive mode

By default, Instacli runs in interactive mode. If there are unknown commandline options, the user is prompted to give input.

cli input-options.cli

? Username Hes
? Password ********

Subcommand support

Easily provide subcommand support by organizing your cli files in directories.

For example, to run the greeting example from the samples directory, you can write

cli samples basic greet

with output:

Hello, World!

You can interactively select which command to run.

cli samples

Use the cursor to select a command

samples has several subcommands.

* Available commands: 
 > basic         Simple Instacli example scripts
   digitalai     Interact with Digital.ai products and services.
   hello         Hello
   http-server   Use Instacli to run web services
   programming   Programming examples in Instacli
   spotify       Spotify API examples

Use the -q option for non-interacivte mode

cli -q samples

will just print the info message:

samples has several subcommands.

Available commands:
  basic         Simple Instacli example scripts
  digitalai     Interact with Digital.ai products and services.
  hello         Hello
  http-server   Use Instacli to run web services
  programming   Programming examples in Instacli
  spotify       Spotify API examples

User interaction

Easily construct user prompts with Instacli.

Here's an example of how to ask the user to pick something from a list, in a file called prompt.cli:

Prompt:
  description: Select a language
  enum:
    - English
    - Spanish
    - Dutch

Print:
  You selected: ${output}

You will be presented with an interactive selector when running it:

cli prompt.cli

? Select a language 
 ❯ ◉ English
   ◯ Spanish
   ◯ Dutch

You selected: English

Variables

Define variables in ${...} syntax and pick and choose content using the path notation.

Code example: Define a variable

${var}:
  name: my variable
  content:
    a: one
    b: two

Print: ${var.content}

will print

a: one
b: two

The output variable

The result of a command is always stored in the variable ${output}.

This makes it easy to pick up in a subsequent command

For example

Code example: Using the output variable

GET: http://localhost:2525/hello

Print: ${output}

Will print the output of the GET request:

Hello from Instacli!

Some commands work directly with the output variable. This helps in having a more declarative and readable script. For example, you don;t need to pass the ${output} variable to the Expected output command.

Code example: Implicit output variable

GET: http://localhost:2525/hello

Expected output: Hello from Instacli!

If you are going to use the output variable later on, best practice is to assign it to a named variable using As .

Code example: Assign output to a named variable

GET: http://localhost:2525/hello
As: ${result}

Print:
  The result of GET /hello was: ${result}

Http Server

For quick API prototyping, Instacli will run an HTTP server for you. Define some endpoints and back them by Instacli scripts:

Code example: Running an HTTP server

Http server:
  port: 2525
  endpoints:
    /hello-example:
      get:
        script:
          Output: Hello from Instacli!

Take a look at the sample server that serves all requests from the Instacli documentation and test suite.

If statement

Instacli supports various programming logic constructs, like 'if', 'repeat', 'for each'

This is what an If statement looks like:

Code example: If statement

If:
  item: this
  equals: that
  then:
    Print: I'm confused!

For each

With For each you can loop over collections and do stuff.

Code example: For each statement

For each:
  ${name} in:
    - Alice
    - Bob
    - Carol
  Print: Hello ${name}!

Output:

Hello Alice!
Hello Bob!
Hello Carol!

You can use For each to transform a list into something else, like the map() function in some programming languages.

Code example: For each to transform a list

For each:
  ${name} in:
    - Alice
    - Bob
    - Carol
  Output: Hello ${name}!

Expected output:
  - Hello Alice!
  - Hello Bob!
  - Hello Carol!

Testing in Instacli

Writing tests in Instacli is straightforward:

Test case: A simple test case

Assert that:
  item: one
  in: [ one, two, three ]

In fact, all tests for the Instacli language and commands are written in Instacli itself and can be found in the instacli-spec directory, in the tests subfolders. For example, take a look at the tests for assertions

Documenting Instacli

All documentation can be found in the instacli-spec directory.

Instacli documentation is in Markdown and contains runnable code that is run as part of the test suite.

Here's an example of Instacli documentation:

## Code examples

The following code prints a message:

```yaml instacli
Print: Hello from Instacli!
```

You can do 'Spec-driven development' with Instacli. For new features, write the documentation first, then run it. Since you haven't implemented anything yet, the test suite will fail. Then write the implementation, and once the tests are green, you're done!