Skip to content

Latest commit

 

History

History
67 lines (43 loc) · 3.57 KB

DEVELOP.md

File metadata and controls

67 lines (43 loc) · 3.57 KB
Raw

Development

Building the Fastly CLI requires Go (version 1.18 or later), and Rust. Clone this repo to any path and type make to run all of the tests and generate a development build locally.

git clone [email protected]:fastly/cli
cd cli
make
./fastly version

The make task requires the following executables to exist in your $PATH:

If you have none of them installed, or don't mind them being upgraded automatically, you can run make dependencies to install them.

New API Command Scaffolding

There are two ways to scaffold a new command, that is intended to be a non-composite command (i.e. a straight 1-1 mapping to an underlying Fastly API endpoint):

  1. make scaffold: e.g. fastly foo <create|delete|describe|update>
  2. make scaffold-category: e.g. fastly foo bar <create|delete|describe|update>

The latter Makefile target is for commands we want to group under a common category (in the above example foo is the category and bar is the command). A real example of a category command would be fastly logging, where logging is the category and within that category are multiple logging provider commands (e.g. fastly logging splunk, where splunk is the command).

The logging category is an otherwise non-functional command (i.e. if you execute fastly logging, then all you see is help output describing the available commands under the logging category).

Makefile target structure:

CLI_PACKAGE=... CLI_COMMAND=... CLI_API=... make scaffold
CLI_CATEGORY=... CLI_CATEGORY_COMMAND=... CLI_PACKAGE=... CLI_COMMAND=... CLI_API=... make scaffold-category

Example usage:

Imagine you want to add the following top-level command fastly foo-bar with CRUD commands beneath it (e.g. fastly foo <create|delete|describe|list|update>), then you would execute:

CLI_PACKAGE=foobar CLI_COMMAND=foo-bar CLI_API=Bar make scaffold

NOTE: Go package names shouldn't have special characters, hence the difference between foobar and the command foo-bar. Also, the CLI_API value will be interpolated into CRUD verbs (CreateBar, DeleteBar etc), along with their inputs (fastly.CreateBarInput, fastly.DeleteBarInput etc).

Now imagine you want to add a new subcommand to an existing category such as 'logging' fastly logging foo-bar with CRUD commands beneath it (e.g. fastly logging foo-bar <create|delete|describe|list|update>), then you would execute a similar command but you would change to the scaffold-category target and also prefix two additional inputs:

CLI_CATEGORY=logging CLI_CATEGORY_COMMAND=logging CLI_PACKAGE=foobar CLI_COMMAND=foo-bar CLI_API=Bar make scaffold-category

NOTE: Within the generated files, keep an eye out for any <...> references that need to be manually updated.

.fastly/config.toml

The CLI dynamically generates the ./pkg/config/config.toml within the CI release process so it can be embedded into the CLI binary.

The file is added to .gitignore to avoid it being added to the git repository.

When compiling the CLI for a new release, it will execute ./scripts/config.sh. The script uses ./.fastly/config.toml as a template file to then dynamically inject a list of starter kits (pulling their data from their public repositories).

The resulting configuration is then saved to disk at ./pkg/config/config.toml and embedded into the CLI when compiled.