Skip to content

Latest commit

 

History

History
222 lines (151 loc) · 5.22 KB

Anatomy of an Instacli file.md

File metadata and controls

222 lines (151 loc) · 5.22 KB
Raw

Anatomy of Instacli files

What does a single Instacli script look like

Hello world example

This is the simplest Instacli file:

Print: Hello world

Instacli files are a list of commands. In this case the file contains a single Print command. By convention, commands start with a capital letter.

If we store it in a file hello-world.cli, we can run it with the following command:

cli hello-world.cli

And get the expected output:

Hello world

It's all YAML

Instacli files are just Yaml.

Instacli files have .cli file extension. Within Instacli, the convention is that .yaml files are for static data and .cli files are Instacli scripts that contain commands. Tip: Map your editor to recognize .cli as .yaml.

Instacli files being Yaml has its pros and cons.

The main idea is to blur the line between 'code' and 'data'. By having the 'data' closer to 'code' it makes it easier to adopt a declarative style: saying what you want to happen rather than how you want it to be carried out. In this style, you would have a higher 'data content' than 'logic content' in your scripts. Ideally, more than 50% of the script is 'data', and the 'logic' is a smaller part. Then Yaml starts making sense as a format.

By convention, commands start with a capital letter, for example Print or Read file, to distinguish them from data.

Another advantage of Instacli syntax being YAML is predictability: if you have worked with Yaml before you know its structure and pitfalls already, and you get editor support out-of-the-box. It's also way easier for the implementation to parse it than a custom format.

Instacli does add some additional formatting on top of Yaml, for example the variable syntax ${..}.

Instacli's Yaml flavor does not rely on special Yaml features like directives. It is used as a human-friendly way of writing JSON.

Multiple commands and ---

You can have multiple commands in a file, and they will be executed in order:

Prompt: What is your name?

Print: Hello ${output}!

When storing this in a file prompt.cli and running it with the following command,

cli prompt.cli

you would get the following:

? What is your name? Hes
Hello Hes!

The commands in a file are just dictionary keys. We run into trouble if we want to use the same key again.

For example, this won't work because it's invalid Yaml:

Print: Hello
Print: Hello again!  # Invalid YAML!

The solution is to add the YAML document separator ---:

Print: Hello
---
Print: Hello again!

It's not very pretty, but it works. This is the best option in most cases.

There are some ways to avoid the --- separator, though.

With most commands you can simply supply the arguments as a list, and they will be executed in sequence:

Print:
  - Hello
  - Hello again!

Another approach is using the Do command, that takes a list of command

Do:
  - Print: Hello
  - Print: Hello again!

You could argue that an Instacli script should have a giant Do on top, and all commands should be specified in the list. That's perfectly fine code, but to me it looks distracting, so I prefer the separator approach. Besides, the separator helps you to visually divide sections in your code if placed strategically.

Script info

You can specify the description of your script with the Script info command.

Take this file simple-greeting.cli:

Script info: Prints a simple greeting

Print: Hi there!

When running it with the --help flag, the description is printed:

cli --help simple-greeting.cli

Prints a simple greeting

Defining script input

Script info is also used to specify input parameters. Here's greet.cli:

Script info:
  description: Prints a personalized greeting
  input:
    name: Your name

Print: Hello ${input.name}!

It has input parameter name:

cli --help greeting.cli

Prints a personalized greeting

Options:
  --name   Your name

And you can invoke it as follows.

cli greeting.cli --name Bob

Hello Bob!

For more information, refer to the Script info command.

Script output

You can set the output of the script with the Output command.

For example, with script hello.cli

Output:
  a: one
  b: two
  c: three

The output is stored in the ${output} variable. When invoking instacli with the --output option, it will be printed:

cli --output hello.cli

a: one
b: two
c: three

You also get it when calling a script from another script:

Run script:
  resource: hello.cli

Expected output:
  a: one
  b: two
  c: three