CLI

The Otterize command line interface (CLI) offers the following capabilities:

• Interact with the Otterize network mapper running in a Kubernetes cluster.
• Transform intents files from plain YAML format to Kubernetes custom resource YAML format.
• Interact with the Otterize Cloud, through its REST API.

This CLI is open-source software. To see its source or build it yourself, see https://github.com/otterize/otterize-cli.

The CLI is available as an installable binary as documented in this guide.

The following are the commands offered by the Otterize CLI.

Command structure

Most CLI commands are of the form otterize NOUN VERB where the NOUN is the type of object (e.g. intents, integrations) and the VERB is the operation being performed. Putting the NOUN first makes the auto-completion and documentation built into the CLI easier to consume: you first choose the type of object you are interested in, then the built-in auto-completion or documentation shows you the options on that type of object.

• otterize -h or otterize --help lists the various object types.
• otterize NOUN -h or otterize NOUN --help offers help on the specified object type.
• otterize NOUN VERB -h or otterize NOUN VERB --help offers help on the specified operation.

otterize completion offers instruction for generating command completions in various shells.

Usage Telemetry

The CLI reports anonymous usage information back to the Otterize team, to help the team understand how the software is used in the community and what aspects users find useful. No personal or organizational identifying information is transmitted in these metrics: they only reflect patterns of usage. You may opt out at any time through a single configuration flag.

To disable sending usage information:

• Using a flag: --telemetry-enabled=false.
• Via an environment variable: OTTERIZE_TELEMETRY_ENABLED=false.

If the telemetry flag is omitted or set to true, telemetry will be enabled: usage information will be reported.

For more information see the Usage telemetry Documentation

Global options

The following options apply to all CLI commands.

Name	Default	Description
-h or --help		Get help on any command.
--api-address	https://app.otterize.com/api	The URL for the Otterize API endpoint.
--client-id		Set the client id, for use in authenticating API calls.
--client-secret		Set the client secret, for use in authenticating API calls.
--config	~/.otterize/config	Use the given path for the Otterize CLI config file.
--debug		Show debug logs.
--interactive	true	Ask for missing flags interactively.
--org-id		Use the given organization id when calling the Otterize API.
--format	text	Output the results of the command as text (text) or JSON (json).
-q or --quiet		Suppress printing the results of the command.
--token		The token to use in authenticating API calls.
--telemetry-enabled	true	Whether to enable sending of anonymous usage telemetry to Otterize or not.

Network mapper

All otterize network-mapper commands share a set of optional flags which will not be repeated in the documentation for each command.

Common options

Name	Default	Description
--mapper-namespace	otterize-system	Specifies the namespace where the mapper service was installed.
--mapper-service-name	otterize-network-mapper	Specifies the name of the mapper service as it was installed.
--mapper-service-name	otterize-service-port	Specifies the port on which the mapper service is listening.

otterize network-mapper reset

Resets the network mapper by deleting all map information built up so far in memory.

otterize network-mapper list [-n <namespace1>,<namespace2>,...]

Return the network map built by the network mapper since it started, or since it was reset, as a list of clients and the servers they call.

Options

Name	Default	Description
-n or --namespaces		Include only clients in these namespaces (comma-separated).

Returns

Here's a partial output from otterize network-mapper list -n otterize-ecom-demo:

cartservice in namespace otterize-ecom-demo calls:
  - redis-cart
checkoutservice in namespace otterize-ecom-demo calls:
  - cartservice
  - currencyservice
  - emailservice
  - paymentservice
  - productcatalogservice
  - shippingservice
frontend in namespace otterize-ecom-demo calls:
  - adservice
  - cartservice
  - checkoutservice
  - currencyservice
  - productcatalogservice
  - recommendationservice
  - shippingservice
loadgenerator in namespace otterize-ecom-demo calls:
  - frontend
recommendationservice in namespace otterize-ecom-demo calls:
  - productcatalogservice

otterize network-mapper visualize [--format=png | --format=jpg] [-n <namespace1>,<namespace2>,...] -o <path>

Return the network map built by the network mapper since it started, or since it was reset, as an image.

Uses GraphViz (specifically go-graphviz) to generate the image.

Options

Name	Default	Description
--format	png	Image output format: "png" or "jpg".
-n or --namespaces		Include only clients in these namespaces (comma-separated).
-o or --output-path		Filename for the image.
--exclude-labels		A list of labels that would exclude services from list/export. example: "include=false"
--exclude-services		A list of service to exclude from list/export. example: "service1,service2"

Returns

Here's the image generated by running otterize network-mapper visualize -n otterize-ecom-demo -o otterize-ecom-demo.png:

otterize network-mapper export [--format] [-n <namespace1>,<namespace2>,...] [-o <path>] [--output-type <output-type>]

Return the network map built by the network mapper since it started, or since it was reset, as YAML client intents file(s) or as JSON file(s).

Options

Name	Default	Description
--format	yaml	Specifies the format for the export: either yaml or json.
-n or --namespaces		Export only clients in these namespaces (comma-separated).
-o or --output	STDOUT	Filename or directory for redirecting the output.
--output-type	single-file	Whether the output should be written as a single file (single-file) or as multiple files in a directory (dir). Requires the -o or --output to point to a directory.
--server		Export only intents for clients that call this server. The server name must be specified with both service name and namespace, in the format <SERVERNAME>.<SERVER_NAMESPACE>. Example: cartservice.otterize-ecom-demo.
--exclude-labels		A list of labels that would exclude services from list/export. Example: include=false would exclude any service labeled with include=false from being included in list/export.
--exclude-services		A list of services to exclude from list/export. Example: service1,service2.

Returns

Here's a partial output from otterize network-mapper export -n otterize-ecom-demo:

apiVersion: k8s.otterize.com/v2beta1
kind: ClientIntents
metadata:
  name: cartservice
  namespace: otterize-ecom-demo
spec:
  workload:
    name: cartservice
    kind: Deployment
  targets:
    - service: 
        name: redis-cart
---
apiVersion: k8s.otterize.com/v2beta1
kind: ClientIntents
metadata:
  name: checkoutservice
  namespace: otterize-ecom-demo
spec:
  workload:
    name: checkoutservice
    kind: Deployment
  targets:
    - service:
        name: cartservice
    - service: 
        name: currencyservice

Login

otterize login [--switch-account] [--switch-org]

Login to Otterize Cloud using a web browser.

If --switch-account is specified, re-authenticating is forced in the browser, so a new user can be chosen.

If --switch-org is specified, and the current user belongs to multiple org, the new org can be chosen interactively.

Options

Name	Default	Description
--switch-account		Login to a different user account than the one currently set.
--switch-org		Switch to a different organization than the one currently set.

Returns

Outputs login process progress messages, including registering a user if needed, creating an org if needed, and setting the user and org to use by default in other commands.

Please login to Otterize using your browser: https://...
Login completed successfully! logged in as: [email protected]

Querying user info from Otterize server
Logged in as Otterize user usr_1234567 ([email protected])
Only 1 organization found - auto-selecting this organization for use.
Selected organization org_1234567
To change your organization selection, log-in again with --switch-org.

Version

otterize version

Prints the CLI build version, and queries the Otterize Cloud for the current Cloud REST API version (e.g. v1) and revision (hash of the current Cloud REST API definition).

Returns

Returns the version of this CLI and the current version and revision of the Otterize Cloud REST API, as well as the version and revision against which this CLI is built.

Note that the Otterize CLI is mostly a thin but useful utility for invoking the Otterize Cloud REST API. API versions that differ by version number may break backwards compatibility, while those that only differ by revision are backwards compatible: revisions add functionality or documentation but preserve all previous functionality.

If only the Cloud API has changed since the CLI was built (revisions don't match), the CLI might be missing some Cloud capabilities.

If also the Cloud API version is later than the CLI version, some CLI commands might fail.

Beta versions of the Cloud API (e.g. v1beta) are volatile: they may change and break backwards compatibility until they are out of beta.

Version: v0.1.1
Current Cloud API:
    version: v1
    revision: 465ba4174008682f54f99e37d0b7791148aade14
This CLI was built against:
    version: v1
    revision: 91efb6f8acb98985fc2b993baa8d279049c8b302

Caution: this CLI was built with a different version/revision of the Otterize Cloud API.
Some Cloud CLI commands may fail.
Upgrade your CLI to the latest build to resolve this issue.

Environments

otterize environments list [-l label1,label2] [-n name]

List all environments, optionally filtered by labels or name.

Options

Name	Default	Description
-l or --labels		Return only the environments that contain all the given labels. A label may be of the form key or key=value.
-n or --name		Filter the list by environment name. Since environment names are unique, this will always return at most one cluster.

Returns

Returns a table of information about the environments.

id             name                     labels            integrations_count applied_intents_count
────────────── ──────────────────────── ───────────────── ────────────────── ─────────────────────
env_yg64fe8ty2 staging                  region-EU                            15
env_glohhjfowc phase 1                                                       1
env_o6tdthl6qz phase 2                                                       2
env_zfndrpvqgp phase 3                                                       3
env_5mzzqxrr2f eks1_default_environment key1,key2=value2                     0
env_lqrcfkam5g phase 0                  phase1                               0

otterize environments get <environment-id>

Returns information about a single environment, specified by its id.

Returns

Returns a table of information about the specified environment.

id             name    labels service count namespaces count declared intents count
────────────── ─────── ────── ───────────── ──────────────── ─────────────────────
env_o6tdthl6qz staging        12            1                2

otterize environments create -n <environment-name> [-l label1,label2]

Creates a new environment with the given name, and optionally with the given labels.

Environment names must be unique in an organization.

The keys of the labels on a given environment must be unique.

Options

Name	Default	Description
-n or --name		The name to give the new environment.
-l or --labels		Label the new environment with the given labels. A label may be of the form key or key=value.

Returns

Returns a table of information about the newly-created environment.

id             name labels                    service count namespaces count declared intents count
────────────── ──── ───────────────────────── ───────────── ──────────────── ──────────────────────
env_bzzustqrek qa   anonymized=true,us-east-1 0             0                0

otterize environments update <environment-id> [-l label1,label2] [-n name]

Updates an environment, specified by its id, optionally changing its name and optionally changing its labels.

Environment names must be unique in an organization.

The keys of the labels on a given environment must be unique.

Options

Name	Default	Description
-l or --labels		Relabel the environment with the specified labels. A label may be of the form key or key=value.
-n or --name		Rename the environment with the specified name.

Returns

Returns a confirmation of the update, and a table of information about the newly-updated environment.

Environment updated
id             name labels                     service count namespaces count declared intents count
────────────── ──── ────────────────────────── ───────────── ──────────────── ─────────────────────
env_bzzustqrek qa1  anonymized=false,us-east-2 0             0                0

otterize environments update add-label <environment-id> --key=<key> [--value=<value>]

Updates an environment, specified by its id, by adding a label.

If a label with the specified key already exists on this environment, with or without a value, it is replaced.

Options

Name	Default	Description
--key		Specifies a key for the added label.
--value		Specifies a value for the added label.

Returns

Returns a table of information about the newly-updated environment.

Environment updated
id             name labels                               service count namespaces count declared intents count
────────────── ──── ──────────────────────────────────── ───────────── ──────────────── ──────────────────────
env_uchr33prjg qa   size=small,anonymized=true,us-east-1 0             0                0

otterize environments update remove-label <environment-id> --key=<key>

Updates an environment, specified by its id, by removing a label.

The label with the specified key is removed whether or not it has a value.

Options

Name	Default	Description
--key		Specifies the key for the label to be removed.

Returns

Returns a table of information about the newly-updated environment.

Environment updated
id             name labels                    service count namespaces count declared intents count
────────────── ──── ───────────────────────── ───────────── ──────────────── ──────────────────────
env_uchr33prjg qa   anonymized=true,us-east-1 0             0                0

otterize environments delete <environment-id>>

Deletes the specified environment.

If the environment is being used as the default environment for a Kubernetes integration, that integration must first be updated with a different environment, or deleted.

Returns

Returns confirmation of the deletion.

Deleted environment env_bzzustqrek

Integrations

otterize integrations list [--cluster-id=<cluster-id>] [--env-id=<env-id>] [--name=<name>] [--type=GENERIC | --type=KUBERNETES]

List all integrations, optionally filtered by cluster, environment, name, or type.

Options

Name	Default	Description
--cluster-id		Show only the integration associated with the specified cluster.
--env-id		Show only the integrations with the specified environment as their default environment.
-n or --name		Show only the integration with the specified name.
--type		Show only integrations with the specified type: GENERIC or KUBERNETES.

Returns