DOCSEARCHbyAlgolia
Submit Docs

Fastly CLI

repository·main·Indexed 41 days ago

https://github.com/fastly/cli

A command-line interface for interacting with the Fastly platform, allowing developers to manage services, configurations, and platform resources. It includes tools for authentication, Compute project management, and AI Runtime Control (ARC) object manipulation, such as managing provider connections and virtual keys.

Tokens
59.4K
Snippets
356
Records
448
Agent score
50%

What's inside Fastly CLI

  1. Manage `.fastly/config.toml` versioning

    main

    The CLI uses an embedded configuration that is merged with the user's local .fastly/config.toml.

    When developing new CLI features that add configuration fields, you must increment the config_version number in the embedded config before publishing a release. This ensures that when users update their CLI, the mismatch between their local version and the new embedded version triggers a merge, updating their local config with the new fields.

    If a user encounters configuration issues, they can use the fastly config --reset command to reset their configuration to a version compatible with their current CLI version.

  2. Authenticate with the Fastly CLI

    main

    You can authenticate the Fastly CLI using the interactive login command or by providing an API token via environment variables.

    To perform an interactive login, use: fastly auth login

    Alternatively, you can set the FASTLY_API_TOKEN environment variable to provide authentication for all commands without interactive prompts.

    fastly auth login

  3. Test Compute commands locally during development

    main

    When developing the CLI and testing it against a Compute project, use the --dir flag with compute commands to prevent the CLI from treating the CLI repository itself as the project directory.

    The --dir flag is supported by:

    • compute build
    • compute deploy
    • compute serve
    • compute publish
    go run cmd/fastly/main.go compute deploy --verbose --dir ../../test-projects/testing-fastly-cli

  4. Submit a feature request for the Fastly CLI

    main

    If you want to suggest improvements to the CLI, submit a feature request. This includes:

    • Suggesting new commands or subcommands based on existing Fastly APIs.
    • Requesting improved error messages or user experience enhancements.
    • Requesting support for third-party integrations.

    Example: "Add a fastly service version validate command, which already exists in the Fastly API."

  5. Build the Fastly CLI from source

    main

    To build the Fastly CLI locally, you need Go (version 1.18 or later) and Rust installed. You can run all tests and generate a development build using the make command.

    If you are missing required linting tools (golint, gosec, or staticcheck), you can run make mod-download to install them automatically.

    git clone git@github.com:fastly/cli
cd cli
make
./fastly version

  6. Run the full test suite including integration tests

    main

    To execute the complete test suite, including integration tests for Compute initialization, building, and deployment, run:

    TEST_COMPUTE_INIT=1 TEST_COMPUTE_BUILD=1 TEST_COMPUTE_DEPLOY=1 TEST_COMMAND=gotest make all

    Note: TEST_COMMAND=gotest is optional and uses gotest to provide improved test output formatting.

  7. Scaffold a new API command

    main

    The CLI provides Makefile targets to scaffold new non-composite commands (direct 1-1 mappings to Fastly API endpoints).

    Top-level commands

    To create a command like fastly foo <create|delete|describe|update>, use the make scaffold target. You must provide CLI_PACKAGE, CLI_COMMAND, and CLI_API environment variables.

    Note on naming:

    • CLI_PACKAGE should not contain special characters (e.g., use foobar for a command named foo-bar).
    • CLI_API is used to interpolate CRUD verbs and input types (e.g., CLI_API=Bar results in CreateBar and fastly.CreateBarInput).

    Categorized commands

    To create a subcommand under an existing category (e.g., fastly logging foo-bar <create|delete|describe|list|update>), use the make scaffold-category target. This requires additional CLI_CATEGORY and CLI_CATEGORY_COMMAND variables.

    After scaffolding, check the generated files for any <...> placeholders that require manual updates.

    # Scaffold a top-level command: fastly foo-bar <create|delete|describe|list|update>
CLI_PACKAGE=foobar CLI_COMMAND=foo-bar CLI_API=Bar make scaffold

# Scaffold a categorized command: fastly logging foo-bar <create|delete|describe|list|update>
CLI_CATEGORY=logging CLI_CATEGORY_COMMAND=logging CLI_PACKAGE=foobar CLI_COMMAND=foo-bar CLI_API=Bar make scaffold-category

  8. Debug failing tests with Delve

    main

    To debug a specific test using Delve, follow these steps:

    1. cd into the package directory containing the _test.go file you wish to debug.
    2. Execute the following command (replacing TestNameGoesHere with your target test):
      TEST_COMPUTE_BUILD=1 dlv test -- -test.v -test.run TestNameGoesHere
    3. Once inside the debugger, you can set breakpoints using relative paths from the package directory. For example:
      break ../../app/run.go:152
    TEST_COMPUTE_BUILD=1 dlv test -- -test.v -test.run TestNameGoesHere

  9. Run the Fastly CLI test suite

    main
    You can run the standard test suite using make test. By default, this executes go test -race ./{cmd,pkg}/... to check for race conditions in the command and package directories.
    make test

  12. Interpret authentication expiration summaries and remediation

    main

    When the CLI detects an authentication issue, it provides human-readable summaries and remediation steps.

    • Summaries: The CLI generates strings like expires in 2 hours or expired 3 days ago based on the current status.
    • Remediation: If a token is expiring or expired, the CLI provides actionable text via ExpirationRemediation(tokenType) to guide the user on how to refresh or re-authenticate.