Version: 1.7

Okteto CLI

The Okteto Command Line Interface is a unified tool to manage your development environments.

Synopsis

$ okteto [options] <command> <subcommand> [parameters]

Use okteto command --help for information on a specific command. The synopsis for each command shows its parameters and their usage. Optional parameters are shown in square brackets.

Options	Values
--loglevel	debug, info, warn, error

The amount of information outputted (defaults to warn).

Advanced configuration

It is possible to handle timeouts from the client side when communicating with the buldkit daemon through the Okteto CLI. To do so, the following environment variables can be modified:

OKTETO_KEEPALIVE_CLIENT_TIME_MS: After this duration of time, if the client doesn't see any activity it will ping the server to see if the transport is still alive. If set below 10s, a minimum value of 10s will be used. The current default value is infinity.
OKTETO_KEEPALIVE_CLIENT_TIMEOUT_MS: After sending a keepalive ping, the client waits for this duration of time and if no activity is seen even after that the connection is closed. The current default value is 20 seconds.
OKTETO_KEEPALIVE_CLIENT_PERMIT_WITHOUT_STREAM: If true, the client sends keepalive pings even with no active RPCs. If false, when there are no active RPCs, Time and Timeout will be ignored and no keepalive pings will be sent. False by default.

Available commands

analytics

Enable / Disable analytics collection. Analytics are enabled by default

$ okteto analytics [parameters]

Options	Description
--disable	Disables analytic collection

Okteto only collects information to help us understand how our users interact with the product. We don't collect any personally identifiable information.

When you use the okteto CLI, the following information is collected:

The name of the action
A timestamp of when it was run
Your version of the CLI
Your OS
An anonymous machine ID (we use https://github.com/denisbrodbeck/machineid for this)
A user ID if you are currently logged in to https://cloud.okteto.com
An action ID (to correlate multiple actions performed during a command's execution)

Please reach out to us if you have any questions or concerns about the information collected.

build

Build and push the images defined in the build section of your okteto manifest:

$ okteto build [service...]

If your okteto context points to an Okteto URL, images are built using the Okteto Build Service. Otherwise, images are built using your local Docker daemon. If you want to use another BuildKit instance, set the variable BUILDKIT_HOST to point to its address, using the format HOST:PORT.

The following flags can be used (very similar to docker build):

Options	Type	Description
--file	(string)	The path to the okteto manifest
--no-cache	(bool)	Do not use cache when building the image (default: `false`)
--secret	(list)	Secret files exposed to the build. Format: `id=mysecret,src=/local/secret`
--export-cache	(string)	Image tag for exported cache when build (optional)
--cache-from	(list)	List of cache source images (optional)

You can also use the -f to point to a Dockerfile. In this mode, okteto build will ignore your Okteto manifest, and directly build the image defined in the Dockerfile. Use this to build images that are not defined on your Okteto manifest.

context

Set the default context.

A context is a group of cluster access parameters. Each context contains a Kubernetes cluster, a user, and a namespace. The current context is the default cluster/namespace for any Okteto CLI command.

$ okteto context

This will prompt you to select one of your existing contexts or to create a new one:

A context defines the default cluster/namespace for any Okteto CLI command.
Select the context you want to use:
Use the arrow keys to navigate: ↓ ↑ → ←
  ▸ https://cloud.okteto.com (Okteto Cloud) *
    minikube
    staging
    production

    Create new context

Options	Type	Description
--token	(string)	API token for authentication. Use this when scripting or if you don't want to use browser-based authentication.
--namespace	(string)	Namespace of your okteto context.
--builder	(string)	URL of the builder service

When you run okteto context, an account will be created for your own URL if it's the first time you set the context in. The CLI will exchange an authorization token with URL and save your API token and Okteto certificates information under $HOME/.okteto/.

Using Environment Variables to authenticate

Environment variables provide another way to specify your credentials. This is the recommended method when scripting tasks or when creating preview environments.

The supported environment variables are:

OKTETO_TOKEN: Specifies the personal access token to use
OKTETO_URL: Specifies the Okteto URL. If missing, it defaults to https://cloud.okteto.com

Available subcommands:

delete

Delete a context.

For example, to delete the Okteto Cloud context, run:

$ okteto context delete https://cloud.okteto.com

list

List available contexts.

$ okteto context list

Name                                            Namespace  Builder                                 Registry
https://cloud.okteto.com *                      cindy      tcp://buildkit.cloud.okteto.net:1234    registry.cloud.okteto.net
minikube                                        default    docker                                  -

show

Print the current context.

$ okteto context show

{
  "name": "https://cloud.okteto.com",
  "token": "REDACTED",
  "namespace": "cindy",
  "builder": "tcp://buildkit.cloud.okteto.net:1234",
  "registry": "registry.cloud.okteto.net",
  "isOkteto": true
}

use

Set the default context.

$ okteto context use

This will prompt you to select one of your existing contexts or to create a new one.

You can also specify an Okteto URL:

$ okteto context use https://cloud.okteto.com

 ✓  Using context cindy @ cloud.okteto.com

Or a Kubernetes context:

$ okteto context use minikube

 ✓  Using context default @ minikube

deploy

Deploy your development environment by running the commands specified in the deploy section of your okteto manifest. If the images in the build section don't exist, okteto deploy automatically builds and pushes all these images. If the repositories in the dependencies section haven't been deployed yet, okteto deploy deploys these dependencies automatically.

The command is executed relative to the path where the manifest is located. This means, that if the manifest is at any subfolder, the pipeline will use the context of the subfolder where the manifest is defined.

$ okteto deploy

Options

Options	Type	Description
--build	(bool)	Force build of images in the `build` section (defaults to `false`)
--dependencies	(bool)	Force deployment of repositories in the `dependencies` section (defaults to `false`)
--file	(string)	The location of the okteto manifest (defaults to `okteto.yml`)
--name	(string)	The name of the development environment (defaults to the repo/folder name)
--namespace	(string)	Overwrites the namespace where the development environment is deployed
--timeout	(duration)	The duration to wait for the development environment deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s)
--var	(list)	Set a pipeline variable (can be set more than once)
--wait	(bool)	Wait until the pipeline finishes (defaults to false)
--no-bash	(bool)	Execute the command using the container's default shell instead of bash (defaults to false)
--remote	(bool)	Run the deploy commands in your Okteto cluster

Executed commands will be executed using bash unless the --no-bash flag has been specified.

destroy

Destroy your development environment. It automatically destroys all the Kubernetes resources created by okteto deploy. If you need to destroy external resources (like s3 buckets or other Cloud resources), use the destroy section of the Okteto Manifest.

$ okteto destroy

Options

Options	Type	Description
--name	(string)	The name of the development environment (defaults to the folder name)
--namespace	(string)	overwrites the namespace where the development environment is deployed
--timeout	(string)	The duration to wait for the development environment to be destroyed. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s)
--volumes	(bool)	Destroy the persistent volumes created by the development environment (defaults to `false`)
--wait	(bool)	Wait until the development environment is destroyed (defaults to `false`)
--no-bash	(bool)	Execute the command using the container's default shell instead of bash (defaults to false)
--all	(bool)	Destroy everything (defaults to `false`)
--remote	(bool)	Run the destroy commands in your Okteto cluster

Executed commands will be executed using bash unless the --no-bash flag has been specified.

Resources annotated with dev.okteto.com/policy: keep will not be affected by the destroy action.

doctor

Generates a doctor file with the okteto logs for a given development container:

$ okteto doctor [devName]

The doctor command should be run from the folder where you ran okteto up.

The doctor file contains:

The okteto.log
The syncthing logs of your development container
A summary of your development container manifest
A metadata file with information about your host machine's OS and architecture

The doctor file is a handy way to collect all the okteto logs. Use it when filing an issue or asking the Okteto community for help.

down

Deactivates your development container, stops the file synchronization service, and restores your previous deployment configuration for a given development container.

$ okteto down [devName]

The down command should be run from the same location as okteto up.

Options	Type	Description
--file	(string)	The path to the okteto manifest (default "okteto.yml")
--namespace	(string)	The namespace to use (defaults to the current okteto context namespace)
--context	(string)	The context to use (defaults to the current okteto context)
--volumes	(bool)	Remove persistent volumes where your local folder is synched on remote

endpoints

List the public endpoints of your development environment.

$ okteto endpoints

Options	Type	Description
--output	(string)	Output format. One of: ['json', 'md']

exec

Executes the COMMAND in your development container. The command will fail if there's no active development container corresponding to the current folder.

$ okteto exec [devName] -- COMMAND

The exec command should be run from the same location as okteto up.

Options	Type	Description
--file	(string)	The path to the okteto manifest (default "okteto.yml")
--namespace	(string)	The namespace to use (defaults to the current okteto namespace)
--context	(string)	The context to use (defaults to the current okteto context)

help

Displays the full help

$ okteto help

init

This command walks you through creating your Okteto Manifest. It only covers the most common items, and tries to guess sensible defaults. See the Okteto Manifest documentation for more details about the Okteto Manifest.

$ okteto init

Options	Type	Description
--file	(string)	The path to the okteto manifest to create (default "okteto.yml")
--replace	(string)	Replace an existing okteto manifest (default `false`)
--namespace	(string)	The namespace to use (defaults to the current okteto context namespace)
--context	(string)	The context to use (defaults to the current okteto context)
-v1	(boolean)	Use the okteto init v1 version (default `false`)

kubeconfig

Download credentials for the Kubernetes cluster selected via okteto context.

$ okteto kubeconfig

 i  Updated kubernetes context 'cloud_okteto_com/cindy' in '/Users/cindy/.kube/config'

namespace

Configure the current namespace of the okteto context.

$ okteto namespace

This will prompt you to select one of your existing namespaces:

Select the namespace you want to use:
Use the arrow keys to navigate: ↓ ↑ → ←
  ▸ cindy

    Create new namespace

 ✓  Using context cindy @ cloud.okteto.com

create

Create a namespace.

This command is only available in clusters that have Okteto installed.

$ okteto namespace create test-cindy

 ✓  Namespace 'test-cindy' created
 ✓  Using context test-cindy @ cloud.okteto.com

delete

Delete a namespace. If the manifest includes destroy commands, they will be executed as part of this command.

This command is only available in clusters that have Okteto installed.

$ okteto namespace delete test-cindy

 ✓  Namespace 'test-cindy' deleted

list

List existing namespace.

This command is only available in clusters that have Okteto installed.

$ okteto namespace list

Namespace       Status
demos-cindy     Active
cindy *         Active

use

Set the default okteto namespace.

$ okteto namespace use cindy

 ✓  Using context cindy @ cloud.okteto.com

pipeline

Pipeline management commands

$  okteto pipeline [command]

Available subcommands:

deploy

Runs a job in the cluster that clones your repository and executes okteto deploy on it. This is equivalent to clicking the Launch Dev Environment button on the Okteto UI and selecting a git repository.

$ okteto pipeline deploy

You need to be logged in to Okteto before running this command.

Options

Options	Type	Description
--branch	(string)	The branch to deploy (defaults to the main branch)
--file	(string)	The location of the okteto manifest. If not set, the automatic deployment rules will be applied.
--name	(string)	The name of the pipeline (defaults to the folder name)
--namespace	(string)	The Kubernetes namespace to use (defaults to the current kube config namespace)
--repository	(string)	The HTTPS url of the repository to deploy (e.g. https://github.com/okteto/movies)
--skip-if-exists	(bool)	Skip the pipeline deployment if the pipeline already exists in the namespace (defaults to `false`)
--timeout	(duration)	The duration to wait for the pipeline to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s)
--var	(list)	Set a pipeline variable (can be set more than once)
--wait	(bool)	Wait until the pipeline finishes (defaults to false)

destroy

Runs a job in the cluster that clones your repository and executes okteto destroy on it. This is equivalent to clicking the Destroy button on the Okteto UI.

$ okteto pipeline destroy

You need to be logged in to Okteto before running this command.

Options

Options	Type	Description
--name	(string)	The name of the pipeline (defaults to the folder name)
--namespace	(string)	The Kubernetes namespace to use (defaults to the current kube config namespace)
--timeout	(string)	The duration to wait for the pipeline to be destroyed. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s)
--volumes	(bool)	Destroy the persistent volumes created by the pipeline (defaults to false)
--wait	(bool)	Wait until the pipeline is destroyed (defaults to false)

preview

Preview environment management commands.

This command is only available in clusters that have Okteto installed.

$  okteto preview [command]

deploy

Deploy an okteto preview environment.

$ okteto preview deploy [name]

Run okteto preview deploy to automatically deploy a preview environment for your branch.

You need to be logged in to Okteto before running this command. Only users with admin access can deploy a global preview environment.

Options	Type	Description
--branch	(string)	The branch to deploy (defaults to your current branch)
--file	(string)	The location of the okteto manifest. If not set, the automatic deployment rules will be applied.
--repository	(string)	The url of the repository to deploy (e.g. https://github.com/okteto/movies) (defaults to your current git configuration repo)
--scope	(string)	The scope of preview environment to create. Accepted values are ['personal', 'global']. A personal preview environment can only be accessed by its creator, while in a global preview environment all cluster users can access it. (defaults to personal)
--sourceUrl	(string)	The HTTPS url of the pull/merge request to deploy.
--timeout	(duration)	The duration to wait for the preview deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s)
--var	(list)	Set a preview environment variable (can be set more than once)
--wait	(bool)	Wait until the preview deployment finishes (defaults to false)

destroy

Destroy your okteto preview environment.

$ okteto preview destroy [name]

Run okteto preview destroy to destroy a given preview environment.

You need to be logged in to Okteto before running this command. Only users with administration privileges can destroy a global preview environment. If the manifest includes destroy commands, they will be executed as part of this command.

endpoints

List the endpoints of a preview environment.

$ okteto preview endpoints [name]

You need to be logged in to Okteto before running this command.

Options	Type	Description
--output	(string)	Output format. One of: ['json']

Output flag can be used to parse the endpoints and add them to your PR with a custom layout.

list

List all your okteto preview environments.

$ okteto preview list

Run okteto preview list to get the status and scope of your preview environments.

You need to be logged in to Okteto before running this command.

logs

Fetch the logs of your development environment.

$ okteto logs [serviceName]

The okteto logs command should be run from the same location than okteto up.

The first argument is optional and it's a regex matching the name of the services you want to fetch the logs from. For example, okteto logs api fetches the logs of any service starting with api.

Options	Type	Description
_--all	(boolean)	Fetch logs from the whole namespace
--exclude	(string)	Exclude by service name (regular expression)
--since	(duration)	Return logs newer than a relative duration like 5s, 2m, or 3h (default 48h0m0s)
--tail	(int)	The number of lines from the end of the logs to show (default 100)
--timestamps	(boolean)	Print timestamps
--file	(string)	The path to the manifest file (default "okteto.yml")
--namespace	(string)	The namespace to use to fetch the logs (defaults to the current okteto namespace)
--context	(string)	The context to use to fetch the logs

restart

Restarts your development pods corresponding to the services section of the okteto manifest for a given development container. This is useful to reload configurations that cannot be hot-reloaded.

$ okteto restart [devName]

The restart command should be run from the same location than okteto up.

Options	Type	Description
--file	(string)	The path to the manifest file (default "okteto.yml")
--namespace	(string)	The namespace to use (defaults to the current okteto namespace)
--context	(string)	The context to use (defaults to the current okteto context)

status

Status of the file synchronization process for a given development container:

$ okteto status [devName] --info

 i  Local syncthing url: http://localhost:60539
 i  Remote syncthing url: http://localhost:60538
 i  Syncthing username: okteto
 i  Syncthing password: ac0ee34a-b1aa-4a41-bc67-cec3128b6cfd
 ✓  Synchronization status: 100.00%

The status command should be run from the same location than okteto up.

Options	Type	Description
--file	(string)	The path to the manifest file (default "okteto.yml")
--namespace	(string)	The namespace to use (defaults to the current okteto namespace)
--context	(string)	The context to use (defaults to the current okteto context)
--info	(bool)	Show syncthing links for troubleshooting the synchronization service
--watch	(bool)	Watch for changes

up

Activate a development container. If needed, okteto up builds the images and runs the deploy commands defined in your Okteto Manifest.

$ okteto up [devName]

When you run okteto up, okteto scales to zero the specified deployment and creates a mirror deployment. The mirror deployment is a copy of the original deployment manifest with the following development-time improvements:

Okteto overrides the container-level configuration of the original deployment with the values defined in your okteto manifest. A typical example of this is to replace the production container image with one that contains your development runtime.
A bidirectional file synchronization service is started to keep your changes up to date between your local filesystem and your development container.
Automatic local and remote port forwarding using SSH. This allows you to do things like access your cluster services via localhost or connect a remote debugger.
A watcher service to keep the definition of the mirror deployment up to date with original deployment.

It's worth noting that your development deployment inherits the original deployment manifest definition. Therefore, the development deployment uses the same service account, environment variables, secrets, volumes, sidecars, ... than the original deployment, providing a fully integrated development environment.

Run okteto down to restore your original deployment.

Options	Type	Description
--file	(string)	The path to the manifest file (default "okteto.yml")
--namespace	(string)	The namespace to use (defaults to the current okteto namespace)
--context	(string)	The context to use (defaults to the current okteto context)
--env	(list)	Set environment variable in the dev container.
--deploy	(bool)	Force execution of the commands in the `deploy` section of the okteto manifest (defaults to `false`)
--reset	(bool)	Resets the file synchronization service. Use it if the file synchronization service stops working.
--command	(list)	The command to execute in the dev container. This overrides the command specified in the `dev` section of the manifest

version

Displays the current installed version

$ okteto version

Troubleshooting

Kubernetes authentication

After you've ran okteto kubeconfig you should be able to communicate with the cluster through tools like kubectl and helm. If you are getting errors when trying to do so, you can use the okteto kubetoken command to troubleshoot the issue. This command is used internally as your authentication plugin against the cluster.

When running

$ okteto kubetoken <okteto_url> <namespace> # example: okteto kubetoken https://cloud.okteto.com cindy-lopez

You should see a message like this:

{
  "apiVersion": "client.authentication.k8s.io/v1",
  "metadata": {
    "creationTimestamp": null,
    "managedFields": [
      {
        "manager": "backend",
        "operation": "Update",
        "apiVersion": "authentication.k8s.io/v1",
        "time": "2023-03-01T13:18:48Z",
        "fieldsType": "FieldsV1",
        "fieldsV1": {
          "f:spec": {
            "f:expirationSeconds": {}
          }
        },
        "subresource": "token"
      }
    ]
  },
  "spec": {
    "audiences": ["<your-cluster-audience>"],
    "expirationSeconds": 1800,
    "boundObjectRef": null
  },
  "status": {
    "token": "<your.jwt.token>",
    "expirationTimestamp": "2023-03-01T13:48:48Z"
  }
}

If you are getting something else, you should be receiving an error message with guidance on how to follow up.

Synopsis​

Advanced configuration​

Available commands​

analytics​

build​

context​

Using Environment Variables to authenticate​

delete​

list​

show​

use​

deploy​

Options​

destroy​

Options​

doctor​

down​

endpoints​

exec​

help​

init​

kubeconfig​

namespace​

create​

delete​

list​

use​

pipeline​

deploy​

Options​

destroy​

Options​

preview​

deploy​

destroy​

endpoints​

list​

logs​

restart​

status​

up​

version​

Troubleshooting​

Kubernetes authentication​

Synopsis

Advanced configuration

Available commands

analytics

build

context

Using Environment Variables to authenticate

delete

list

show

use

deploy

Options

destroy

Options

doctor

down

endpoints

exec

help

init

kubeconfig

namespace

create

delete

list

use

pipeline

deploy

Options

destroy

Options

preview

deploy

destroy

endpoints

list

logs

restart

status

up

version

Troubleshooting

Kubernetes authentication