-
Notifications
You must be signed in to change notification settings - Fork 66
CLI Proposal: verb noun structure
Jade Redworth edited this page Jun 6, 2018
·
21 revisions
This proposal suggests changing the Fn CLI from a [noun][verb] structure to a [verb][noun] structure. Resulting in a more intuitive, human-readable approach that would bring a consistent feel to the CLI. It is a common pattern among other CLI's that developers may be using alongside Fn. A more detailed analysis of the Fn CLI and other CLI's can be found: CLI Analysis.
The Verb Noun matrix shows how many of the nouns that are self-contained and unrelated to a verb. Therefore these should be their own high-level commands along with all other verbs:
| self-contained nouns | verbs |
|---|---|
| start | create |
| update | delete |
| build-server | list |
| init | update |
| deploy | bump |
| test | inspect |
| help | get |
| run | unset |
| call | |
| build |
With the second-level commands referring to the groups:
| second-level nouns |
|---|
| apps / app |
| routes / route |
| calls / call |
note:
There is confusion about the use of apps/routes vs app/route (singular use of app/route/call/image). Looking back at Singular vs Plural the use of both plural and singular nouns are both valid:
~ $ fn create app/apps <app>
~ $ fn delete route/routes <app> </route>
When using 'fn get' and 'fn list', get is used to return a single object, specificly a function call, and list is used to return multiple apps/routes/calls etc. The command 'inspect' allows you to retrieve on or all apps/routes properties. However, this essentially performs the same as 'get' and will, therefore, be deprecated.
~ $ fn list apps
java-app
string-reverse-app
~ $ fn list routes java-app
/hello-java-function <dockerhub_username>/hello2:0.0.2 localhost:8080/r/java-app/hello-java-function
/test-route <dockerhub_username>/hello2:0.0.2 localhost:8080/r/java-app/test-route
~ $ fn list calls <app>
ID: 01C9RQPM7G47WG200000000000
App: java-app
Route: /hello-java-function
Created At: 2018-03-29T11:18:49.840Z
Started At: 2018-03-29T11:18:50.366Z
Completed At: 2018-03-29T11:18:50.367Z
Status: success
ID: 01C9RG0N7147WGA00000000000
App: java-app
Route: /test-route
Created At: 2018-03-29T09:04:29.921Z
Started At: 2018-03-29T09:04:30.432Z
Completed At: 2018-03-29T09:04:30.441Z
Status: success
All subcommands of 'fn images' exist as top-level commands, this makes the use of images redundant and will be deprecated:
~ $ fn images build/bump/call/deploy/push/run/test ...
~ $ fn build/bump/call/deploy/push/run/test ...
Its common practice for other CLI's to logically group commands together within the help text, this makes it easier for developers to scan through a more structure help text.
| Management | Development | Server | Other | Deprecated |
|---|---|---|---|---|
| create | build | build-server | help | apps |
| delete | bump | start | version | routes |
| get | call | stop | inspect | |
| list | deploy | calls | ||
| unset | init | logs | ||
| update | push | images | ||
| run | test |
The result of 'fn help' would be as follows:
Fn command line tool
ENVIRONMENT VARIABLES:
FN_API_URL - Fn server address
FN_REGISTRY - Docker registry to push images to, use username only to push to Docker Hub - [[registry.hub.docker.com/]USERNAME]
SERVER COMMANDS:
build-server builds custom fn server
start start a functions server
start stop a functions server
MANAGEMENT COMMANDS:
create, c create a new object
delete, d delete an object
get, g get information or properties for an object
list, l list all instances of an object
set, s set features or properties for an object
unset unset features or properties for an object
update, u update an object
DEVELOPMENT COMMANDS:
build build function version
bump bump function version
call call a remote function
deploy deploys a function to the functions server. (bumps, build, pushes and updates route)
import import an existing external function
init create a local func.yaml file
push push function to Docker Hub
run run a function locally
test run functions test if present
OTHER COMMANDS:
help shows a list of commands or help for one command
version displays server and cli versions
DEPRECATED COMMANDS:
apps
calls
images
inspect
logs
routes
GLOBAL OPTIONS:
--verbose, -v use --verbose to enable verbose mode for debugging
--help, -h show help
--version print only the cli version
LEARN MORE:
https://github.com/fnproject/fn
COMMANDS:
app create a new app
route create a new route
EXAMPLE:
fn create app <app>
fn create route <app> </path>
COMMANDS:
app delete an app
route delete a route
EXAMPLE:
fn delete app <app>
fn delete route <app> </path>
COMMANDS:
app create an app
route update a route
server update server (pulls latest version)
EXAMPLE:
fn update app <app>
fn update route <app> </path>
fn update server
COMMANDS:
app get a specified app
route get a specified route
config get configuration for apps and routes
call get a specified call
logs get logs for a call
EXAMPLE:
fn get app <app>
fn get route <app> </path>
fn get config app <app> <key>
fn get call <app> <call-id>
fn get logs <app> <call-id>
COMMANDS:
config set configuration for apps and routes
EXAMPLE:
fn set config app <app> <key> <value>
fn set config route <app> </path> <key> <value>
COMMANDS:
config unset configuration for apps and routes
EXAMPLE:
fn unset config app <app> <key>
fn unset config route <app> </path> <key>
COMMANDS:
apps display all apps
routes display all routes for specific
calls display all calls
config display all configs for apps and routes
EXAMPLE:
fn list apps
fn list routes <app> (specific to an app)
fn list calls <app> (specific to an app)
fn list config <app>
fn list config <app> </path>
NAME:
fn run - run a function locally
USAGE:
fn run [command options] [arguments...]
OPTIONS:
--env value, -e value select environment variables to be sent to function
--link value select container links for the function
--method value http method for function
--format default format to use. default and `http` (hot) formats currently supported.
--runs runs for hot functions only, will call the function runs times in a row. (default: 0)
--memory value RAM to allocate for function, Units: MB (default: 0)
--no-cache Don't use Docker cache for the build
NAME:
fn test - run functions test if present
USAGE:
fn test [command options] [arguments...]
OPTIONS:
--remote value run tests against a remote fn server
--all app.yaml if in root directory containing app.yaml, this will deploy all functions
EXAMPLE:
fn call <app> </path>
NAME:
fn init - create a local func.yaml file
USAGE:
fn init [command options] [FUNCTION_NAME]
DESCRIPTION:
Creates a func.yaml file in the current directory.
OPTIONS:
--name value name of the function. Defaults to directory name in lowercase.
--force overwrite existing func.yaml
--runtime value choose an existing runtime - dotnet, go, java8, java9, java, lambda-nodejs4.3, lambda-node-4, node, php, python, python3.6, ruby, rust, kotlin
--entrypoint value entrypoint is the command to run to start this function - equivalent to Dockerfile ENTRYPOINT.
--cmd value command to run to start this function - equivalent to Dockerfile CMD.
--version value set initial function version (default: "0.0.1")
--image value, -i value image name
--memory value, -m value memory in MiB (default: 0)
--type value, -t value route type - sync or async
--config value, -c value route configuration
--headers value route response headers
--format value, -f value hot container IO format - default or http
--timeout value route timeout (eg. 30) (default: 0)
--idle-timeout value route idle timeout (eg. 30) (default: 0)
NAME:
fn deploy - deploys a function to the functions server. (bumps, build, pushes and updates route)
USAGE:
fn deploy [command options] [arguments...]
OPTIONS:
--app value app name to deploy to
--verbose, -v verbose mode
--no-cache Don't use Docker cache for the build
--local, --skip-push does not push Docker built images onto Docker Hub - useful for local development.
--registry --registry username Sets the Docker owner for images and optionally the registry. This will be prefixed to your function name for pushing to Docker registries. eg: --registry username will set your Docker Hub owner. `--registry registry.hub.docker.com/username` will set the registry and owner.
--all app.yaml if in root directory containing app.yaml, this will deploy all functions
NAME:
fn bump - bump function version
USAGE:
fn bump [command options] [arguments...]
OPTIONS:
--major bumps major version
--minor bumps minor version
--verbose, -v verbose mode
NAME:
fn build - build function version
USAGE:
fn build [command options] [arguments...]
OPTIONS:
-v verbose mode
--no-cache Don't use docker cache
NAME:
fn push - push function to Docker Hub
USAGE:
fn push [command options] [arguments...]
OPTIONS:
-v verbose mode
--registry --registry username Sets the Docker owner for images and optionally the registry. This will be prefixed to your function name for pushing to Docker registries. eg: --registry username will set your Docker Hub owner. `--registry registry.hub.docker.com/username` will set the registry and owner.
NAME:
fn start - start a functions server
USAGE:
fn start [command options] [arguments...]
OPTIONS:
--log-level value --log-level debug to enable debugging
--detach, -d Run container in background.
--env-file value Path to Fn server configuration file.
NAME:
fn stop - stop a functions server
USAGE:
fn stop
NAME:
fn build-server - build custom fn server
USAGE:
fn build-server [command options] [arguments...]
OPTIONS:
-v verbose mode
--no-cache Don't use docker cache
--tag value, -t value image name and optional tag
NAME:
fn version - displays cli and server versions
USAGE:
fn version [arguments...]
EXAMPLE:
fn help
fn help create
fn help apps
~ $ fn init --runtime java <app>
~ $ fn run
~ $ fn create route <app> </path> --image <image>
~ $ fn list routes <app>
~ $ fn deploy --app <app>
~ $ fn call <app> </path>
~ $ fn list calls <app>
~ $ fn get calls <app> <call-id>
~ $ fn get logs <app> <call-id>
~ $ fn inspect app <app>
~ $ fn inspect route <app> </path>
~ $ fn list calls <app>
~ $ fn get calls <app> <call-id>
~ $ fn config app <app> <key> <value>
~ $ fn config route <app> </path> <key> <value>
~ $ fn get config app <app> </path> <key>
~ $ fn get config route <app> </path> <key>
~ $ fn unset config app <app> <key>
~ $ fn unset config route <app> </path> <key>
~ $ fn list config apps <app>
~ $ fn list config routes <app> </path>