Skip to content

CLI Analysis

Jump to bottom
Jade Redworth edited this page Apr 3, 2018 · 8 revisions

This document provides analysis for the Fn CLI, comparisons to other cloud functions CLI's and other CLI's, such as Kubernetes, Docker, and Git.

Existing Hierarchal Structure

The current Fn CLI structure is:

fn <verb> [<noun>]
fn [group | noun-plural] [command]

Alternative structures:

1. A more consistent style: 
fn create [ app | route | context | ? ]
fn list [ apps | calls | routes]
fn set [ config | context | ? ]
2. Enforcing the gcloud model: 
fn apps [ create | inspect | list | etc]
fn context [ create | import | use | etc]
fn server [ start | stop | update ]
3. Take the existing hierarchy and clean it up by singularizing the group names and having the plural as a top-level list-style command.
fn app [create | update | etc]
fn apps <-- does a list operation.
4. Following the base structure of option 3 but grouping the and together, which is the CloudFoundry model: 
fn create-app
fn delete-route
fn deploy-app

Verb to Noun matrix

This is useful to see if it makes sense to group together verbs for specific nouns. From the table below apps and routes are the only 2 nouns that share common verbs. With many of the other verbs and nouns having no connection to each other.

Verb start update build-server init apps routes images lamba calls deploy logs test help call build
create ✔️ ✔️
call ✔️ ✔️
delete ✔️ ✔️
list ✔️ ✔️ ✔️ ✔️
update ✔️ ✔️
deploy ✔️
bump ✔️
test ✔️
inspect ✔️
config ✔️ ✔️
*set ✔️
*get ✔️
*list ✔️
*unset ✔️
get ✔️
lambda ✔️

Singular vs Plural vs Both

When using a command such as 'create, update, delete' that are only applicable to a singular app is it reasonable to use the plural 'apps'. Within the help text of the fn CLI for these commands, they are referred to as doing a single command. Should we use apps to determine multiple objects that can be affected and apps for singular commands? On the other hand, should we support both apps and app?

Comparison to other CLI's:

When compared to other cloud function providers the Fn CLI is structured similarly.

Oracle Cloud Infrastructure (OCI) CLI

The OCI CLI syntax groups the commands by type, such as instance, bucket, etc, dependant on their service. This follows the same structure as Fn CLI.

oci <service> <type> <action> <options>
oci compute instance launch
oci os bucket create

Google Cloud Functions (gcloud)

Gcloud structure their CLI similarly to that of Oracle Cloud Infrastructure and Fn CLI:

gcloud <group> <command>

Cloud Foundry (cf)

Cf follows a different structure, they include the and into a singular command, such as 'cf delete-routes' rather than 'cf / . This is a sensible structure way when there is a large amount of groups that share common commands. They also use the plural of the group to list routes/apps/services making the command redundant.

cf <global options> <command> <arguments> <command options>
cf delete <APP_NAME>
cf delete-route <DOMAIN>
cf create-spaces <SPACE>

Docker, Kubernetes, Git

However, when comparing the Fn CLI to Docker, Kubernetes, and Git, which developers may typically be using alongside Fn and may already be familiar with, they are structured in the opposite way. Kubernetes use the structure:

kubectl <command> <type> <name>
kubectl create service foo

Where command specifies the operation that you want to perform: create, get, delete, list. Type specifies the resource you wish to perform this command such as pod/pods. Docker also uses a similar structure:

docker  <command> <args> 
docker start CONTAINER

However, git is similar to that of Kubernetes and docker:

git <command> <args>
git pull origin master

but typically structures their common commands similar to fn CLI.

git <group> <command>
git branch x
git remote x

CLI Syntax Comparison Matrix

Fn Oracle Cloud Infrastructure Google Cloud Functions CloudFoundry Kubernetes Docker Git
noun, verb ✔️ ✔️ ✔️
verb, noun ✔️ ✔️ ✔️
noun-verb ✔️

Logical Groupings

Both Kubernetes and Git use the concept of grouping logical commands together within the help text of the CLI's. This is a structured way to aid the developers in understanding and using the CLI

  • Troubleshooting and debugging commands
  • Informational commands
  • Settings / Configuration commands
  • Deploy commands (although more specific to Kubernetes)
  • Tiers commands such as:
    • Basic
    • Intermediate
    • Advanced

Suggested Groupings

Currently, the Fn CLI lists their commands in an unstructured way, it would be beneficial to group the commands.

Server
  • start
  • update
  • build-server
Groups
  • apps
  • calls
  • init
  • routes
  • images
  • lambda
  • deploy
  • test
Informational
  • logs
  • version
  • help

Suggested initial changes to CLI

The help text within the CLI should be consistent throughout and easy to read.

  • There are commands missing from the help text which should be included:
    • build
    • run
    • call
  • The help text for groups that share common commands should be ordered the same.
  • Tidy up any duplicate commands.

Suggested further changes

To note

  • fn logs help text - 'manage function calls for apps' which is the wrong help text.
  • All sub-commands of 'fn images' exist as top-level commands
Clone this wiki locally