Organizing Instacli files in directories.md

Organizing multiple Instacli files in directories

With multiple files in a directory, you can run the directory as a cli command. The Instacli scripts will be subcommands.

For this example we run from the samples directory. It contains a directory basic with the following files:

create-greeting.cli
greet.cli
greeting.yaml
multiple-choice.cli
output.cli
simple-question.cli

We can now run basic as a cli command with subcommands for each of the files. First, let's use the --help option to see some more descriptions

cli --help basic

Simple Instacli example scripts

Available commands:
  create-greeting   Creates a greeting and puts it in the output
  greet             Prints a greeting
  multiple-choice   Interaction example
  output            Sets test output
  prompt            Simple interactive prompt

We can now invoke the greet command like this:

cli basic greet

With the expected output:

Hello, World!

Note that it's optional to specify the .cli extension. The following three commands are equivalent:

cli basic greet

cli basic greet.cli

cli basic/greet.cli

Interactive command chooser

When invoking a directory without the --help parameter, Instacli lets you select the command with an interactive prompt. This is a great way to explore the commands and subcommands!

cli basic       

Simple Instacli example scripts

* Available commands: 
 > create-greeting          Creates a greeting and puts it in the output
   greet                    Prints a greeting
   output                   Sets test output
   prompt-multiple-choice   Interaction example
   prompt-simple-question   Simple interactive prompt

Calling another Instacli script

We showed above that you can call another Instacli script from within an Instacli script with the Run script command.

Another way is to use it as a regular command. Instacli reads all cli files in the same directory and makes them available as commands in the current script. While doing so, it transforms file names in "kebab-style" to "Sentence style".

For example, suppose we have a file create-greeting.cli, that creates a greeting and puts it in the output:

Script info:
  description: Creates a greeting
  input:
    name: Your name

Output: Hello ${input.name}!

We can now call it as Create greeting from a script in the same directory:

Code example: Calling another cli file

Create greeting:
  name: Cray

Expected output: Hello Cray!

The .instacli.yaml file

Each directory can have a .instacli.yaml file that contains metadata about the directory.

You can give the directory a readable description, import cli files from other directories and manage http connection data.

Directory description

Add a .instacli.yaml file to the directory to give a description to the current directory.

Script info: This is an example directory

The information is printed when displaying help for the directory:

cli --help .

This is an example directory

Available commands:
  create-greeting   Creates a greeting
  say-something     Say something

Hidden directory

You can hide the directory from the interactive command chooser by setting the hidden property to true.

For example take the following .instacli.yaml file in the subcommand directory:

Script info:
  hiddent: true

It will not show up as a subcommand when invoking cli --help.

Instacli version

You can indicate the version of the Instacli spec that the script is using.

Script info:
  instacli-spec: v0.1

Importing files from another directory

Out-of-the-box, you can call a script from within the same directory as a regular Instacli command.

To call a script from another directory, you can import it in the .instacli.yaml file. This will import it for all scripts in that directory.

For example, if we have the file helper/say-something.cli:

Output: Something ${input.what}

And we have it in the .instacli.yaml file as follows:

Script info: This is an example directory

imports:
  - helper/say-something.cli

Then you can call it like this from your script:

Code example: Calling a script that was imported from another directory

Say something:
  what: funny

Expected output: Something funny

Specifying connection data

The .instacli.yaml file also contains a connections settings for retrieving HTTP connection credentials. See the Connect to command for more details.