CLI

Command Line Interface

The Shimoku command line interface (CLI) is a tool that comes with the python package installation, it makes it easier to use certain functionalities that don't need to be in a script.

To confirm that it is installed use the shimoku keyword in a terminal in your environment, then the following help message will appear:

usage: shimoku [-h] [--interactive] [--shell-commands-enabled] 
                    {config,playground,cloud,persist} ...

This is the Shimoku cli, it is used to interact with the Shimoku services

positional arguments:
  {config,playground,cloud,persist}
                        Available commands
    config              Commands to configure the SDK access
    playground          Commands to interact with the playground
    cloud               Commands to interact with the cloud
    persist             Commands to persist the contents of the current database

optional arguments:
  -h, --help            show this help message and exit
  --interactive, -i     Run in interactive mode
  --shell-commands-enabled, -s
                        Enable the possibility to run shell commands from the 
                        interactive mode

The CLI is self-documenting so if you have any doubt about a particular command just type -h or --help after the command for information on what it does and how to use it.

The commands are separated in different command groups that can have multiple inner commands. The first layer (shimoku) branches into four possible command groups:

• config - These are the commands that will be used to manage the configuration variables needed to access workspaces.

• playground - These commands are used to manage the local server that serves the playground, it can initiate a server and if needed can terminate a server that runs on the background (mostly for handling previous versions servers)

• cloud - These commands handle anything that has to interact with the API directly; creating, deleting, updating and getting resources from the API. (Can interact with the local server too, depending on the configuration variables)

• persist - These commands group the code generation functionalities, to use the database as the source of truth.

Configuration

First you will want to set your default configuration, using the credentials of the main workspace that you will be working with.

Use the following command to set the default configuration:

> shimoku config set

It will then ask for the credentials:

> access_token: YOUR-ACCESS-TOKEN
> universe_id: YOUR-UNIVERSE-ID
> workspace_id: YOUT-WORKSPACE-ID

It will check check if the parameters are correct and if they are it will save them, you will know because it will output this message:

> The configuration parameters are valid, saving them...

You can save multiple profiles identified with different names by using the parameter --profile, a recommendation is to create the profile local to interact with the playground workspace:

> shimoku config set --profile local
> access_token: local
> universe_id: local
> workspace_id: local
> The configuration parameters are valid, saving them...

After that you should have at least two profiles, you can see your profiles and which one you are using by executing the command:

> shimoku config list-profiles

        Profiles
  ┏━━━━━━━━━┳━━━━━━━━━┓ 
  ┃ Profile ┃ Current ┃ 
  ┡━━━━━━━━━╇━━━━━━━━━┩ 
  │ default │         │ 
  │ local   │ X       │ 
  └─────────┴─────────┘       

Also you can retrieve the configuration values with the command:

> shimoku config get

              Local Configuration Variables
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓ 
┃ ENVIRONMENT ┃ ACCESS_TOKEN ┃ UNIVERSE_ID ┃ WORKSPACE_ID ┃ 
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩ 
│ production  │ local        │ local       │ local        │ 
└─────────────┴──────────────┴─────────────┴──────────────┘               

Interactive

The interactive mode is the recommended way to use the CLI, as it has some useful functionalities that the default mode does not provide.

To enter the interactive mode the main shimoku parser has to recieve the flag -i or --interactive:

> shimoku -i

Then the view will change and will show you the profile being used in uppercase with an S- in front, in the case of being in the local profile:

S-LOCAL> _

Word Completion

By pressing the tab at any moment the CLI will recommend the possible completion options:

S-LOCAL> _
         | config      
         | playground  
         | cloud       
         | persist     
         | --help      
         | -h          

It will use the current text in the line to guess what you are trying to write, if it cant find nothing then it wont display any options:

S-LOCAL> cloud delete men_
                         | menu-path   
                         | menu-paths  

Use the arrows to select between the options, and the tab to select the option you want.

Session Variables

In the interactive mode you can store session variables that later can be used in the commands, the following syntax has to be used to set variables:

S-LOCAL> $ MY_VAR_1 MY_VALUE_1 MY_VAR_2 MY_VALUE_2

Then the key variables will be replaced in the execution of the command when a $ is put before them:

cloud create menu-path --name $MY_VAR_1 
    v
    v replace variables
    v
cloud create menu-path --name MY_VALUE_1

These variables will be recommended as options for the arguments of the commands:

S-LOCAL> cloud create menu-path --name _
                                       | $MY_VAR_1  
                                       | $MY_VAR_2

An example on how this can be useful is if you have to access temporarily to a different workspace:

S-LOCAL> $ my_other_workspace OTHER_WORKSPACE_ID

Variable my_other_workspace set to OTHER_WORKSPACE_ID

S-LOCAL> cloud list menu-paths --workspace-id $my_other_workspace

The other feature of the variables is that they will be used automatically if no value has been set for a parameter of a command but the variable with the same name exists, so for example, if the local server is running in a port different from 8000 you can set it as a variable and every call will use that value for the port parameter.

The values passed to parameters will always override the configuration variables or environment variables, and every function accepts variables from higher levels if they need them, for example when creating a menu path you can also specify the universe and access_token for that specific command.

S-LOCAL> $ local_port 8080

Variable local_port set to 8080

S-LOCAL> cloud create menu-path --name MyMenuPath
2024-02-09 15:59 | INFO | Using saved value for unspecified argument local_port
2024-02-09 15:59 | INFO | Starting execution: get_menu_path
2024-02-09 15:59 | INFO | Created menu path MyMenuPath with id ec0c4820-073a-4881-b3bb-e7517da4b992
2024-02-09 15:59 | INFO | Finished execution: get_menu_path, elapsed time: 4.74 ms

For this reason the CLI will recommend some options when assigning variables, that might be of interest:

S-LOCAL> $ _
           | environment   
           | access_token  
           | universe_id   
           | workspace_id  
           | local_port    
           | menu_path     
           | board         
           | activity