github.com/fastly/cli@v1.7.2-0.20240304164155-9d0f1d77c3bf/DEVELOPMENT.md (about)

     1  ## Development
     2  
     3  Building the Fastly CLI requires [Go](https://golang.org) (version
     4  1.18 or later), and [Rust](https://www.rust-lang.org/). Clone this
     5  repo to any path and type `make` to run all of the tests and generate
     6  a development build locally.
     7  
     8  ```sh
     9  git clone git@github.com:fastly/cli
    10  cd cli
    11  make
    12  ./fastly version
    13  ```
    14  
    15  The `make` task requires the following executables to exist in your `$PATH`:
    16  
    17  - [golint](https://github.com/golang/lint)
    18  - [gosec](https://github.com/securego/gosec)
    19  - [staticcheck](https://staticcheck.io/)
    20  
    21  If you have none of them installed, or don't mind them being upgraded automatically, you can run `make dependencies` to install them.
    22  
    23  ### New API Command Scaffolding
    24  
    25  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):
    26  
    27  1. `make scaffold`: e.g. `fastly foo <create|delete|describe|update>`
    28  2. `make scaffold-category`: e.g. `fastly foo bar <create|delete|describe|update>`
    29  
    30  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).
    31  
    32  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).
    33  
    34  **Makefile target structure:**
    35  
    36  ```bash
    37  CLI_PACKAGE=... CLI_COMMAND=... CLI_API=... make scaffold
    38  CLI_CATEGORY=... CLI_CATEGORY_COMMAND=... CLI_PACKAGE=... CLI_COMMAND=... CLI_API=... make scaffold-category
    39  ```
    40  
    41  **Example usage:**
    42  
    43  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:
    44  
    45  ```bash
    46  CLI_PACKAGE=foobar CLI_COMMAND=foo-bar CLI_API=Bar make scaffold
    47  ```
    48  
    49  > **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).
    50  
    51  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:
    52  
    53  ```bash
    54  CLI_CATEGORY=logging CLI_CATEGORY_COMMAND=logging CLI_PACKAGE=foobar CLI_COMMAND=foo-bar CLI_API=Bar make scaffold-category
    55  ```
    56  
    57  > **NOTE**: Within the generated files, keep an eye out for any `<...>` references that need to be manually updated.
    58  
    59  ### `.fastly/config.toml`
    60  
    61  The CLI dynamically generates the `./pkg/config/config.toml` within the CI release process so it can be embedded into the CLI binary.
    62  
    63  The file is added to `.gitignore` to avoid it being added to the git repository.
    64  
    65  When compiling the CLI for a new release, it will execute [`./scripts/config.sh`](./scripts/config.sh). The script uses [`./.fastly/config.toml`](./.fastly/config.toml) as a template file to then dynamically inject a list of starter kits (pulling their data from their public repositories).
    66  
    67  The resulting configuration is then saved to disk at `./pkg/config/config.toml` and embedded into the CLI when compiled.
    68  
    69  When a user installs the CLI for the first time, they'll have no existing config and so the embedded config will be used. In the future, when the user updates their CLI, the existing config they have will be used.
    70  
    71  If the config has changed in any way, then you (the CLI developer) should ensure the `config_version` number is bumped before publishing a new CLI release. This is because when the user updates to that new CLI version and the invoke the CLI, the CLI will identify a mismatch between the user's local config version and the embedded config version. This will cause the embedded config to be merged with the local config and consequently the user's config will be updated to include the new fields.
    72  
    73  > **NOTE:** The CLI does provide a `fastly config --reset` option that resets the config to a version compatible with the user's current CLI version. This is fallback for users who run into issues for whatever reason.
    74  
    75  ### Running Compute commands locally
    76  
    77  If you need to test the Fastly CLI locally while developing a Compute feature, then use the `--dir` flag (exposed on `compute build`, `compute deploy`, `compute serve` and `compute publish`) to ensure the CLI doesn't attempt to treat the repository directory as your project directory.
    78  
    79  ```shell
    80  go run cmd/fastly/main.go compute deploy --verbose --dir ../../test-projects/testing-fastly-cli
    81  ```