Version: 1.25

Okteto CLI

The Okteto Command Line Interface (CLI) is a unified tool to manage your applications in Okteto directly from your terminal. Follow this guide to download and install the CLI if you don't already have it. The CLI is an open-source tool that can be used independently or integrated with the Okteto Platform.

Commands labeled Platform are available exclusively on the Okteto platform and require the Okteto Helm Chart to be installed in your Kubernetes cluster
Commands labeled Open-Source are available to users of the Okteto open-source CLI

For a complete comparison of features, refer to the open-source README

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.

Global Flags

Options	Type	Description	Default
--help	bool	Show help info
-l, --log-level	debug, info, warn, error	Amount of information output	warm
--log-output	tty, plain, json	Output format for logs	tty

Available commands

analytics
PlatformOpen-Source

Enable / Disable analytics collection. Analytics are enabled by default.

If telemetry is disabled, analytics are disabled for all developers.

$ okteto analytics [parameters]

Options	Description
-d, --disable	Disable 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 Okteto
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
Platform

Build and push the images defined in the build section using the Okteto Build Service.

$ okteto build [image...]

The following command flags are available:

Options	Type	Description	Default
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
-n, --namespace	string	Overwrite the current Okteto Namespace
--no-cache	bool	Do not use cache when building the image	`false`
--progress	string	Show plain/tty build output	`tty`

You can also use the -f to point to a Dockerfile instead of an Okteto Manifest. In this mode, okteto build will build an image using the Dockerfile. This is useful to build images that are not defined on your Okteto manifest.

In "Dockerfile" mode, the following additional flags can be used (very similar to docker build):

Options	Type	Description
--build-arg	list	Set build-time variables (optional)
--cache-from	list	List of cache source images (optional)
--export-cache	string	Image tag for exported cache when build (optional)
--platform	string	Specify which platform to build the container image for (optional)
--secret	list	Secret files exposed to the build. Format: `id=mysecret,src=/local/secret`
-t, --tag	string	Tag name to be pushed (optional)
--target	string	Target build stage to build (optional)

context
PlatformOpen-Source

Set the default Okteto Context.

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

$ okteto context

tip

okteto ctx is an alias of okteto context.

This will prompt you to select one of your existing Okteto 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://okteto.example.com *
    minikube

    Create new context

Options	Type	Description	Default
--insecure-skip-tls-verify	bool	Skip validation of server's certificates	`false`
-n, --namespace	string	Overwrite the current Okteto Namespace
--token	string	API token for authentication. Use this when scripting or if you don't want to use browser-based authentication.

When you run okteto context, the Okteto CLI will exchange an authorization token with the Okteto Platform and save your API token and Okteto certificates information under $HOME/.okteto/.

tip

In your CI/CD you should use environment variables to specify your Okteto Context, Namespace and token. Check out Environment Variables to know more.

Available subcommands:

delete

Delete one or more Okteto Contexts.

For example, to delete the Okteto Context "https://okteto.example.com", run:

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

list

List available Okteto Contexts.

$ okteto context list

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

Options	Type	Description	Default
-o, --output	string	Output format. One of: `json`, `yaml`	`json`

show

Print the current Okteto Context.

$ okteto context show

Options	Type	Description	Default
--include-token	bool	Include the token in the output	`false`
-o, --output	string	Output format. One of: `json`, `yaml`	`json`

{
  "name": "https://okteto.example.com",
  "token": "REDACTED", # only printed using flag: --include-token
  "namespace": "cindy",
  "builder": "tcp://buildkit.okteto.example.com:1234",
  "registry": "registry.okteto.example.com",
  "isOkteto": true
}

use

Set the default Okteto Context. okteto context use is an alias of okteto context.

deploy
Platform

Deploy your Development Environment by running the commands specified in the deploy section of your Okteto Manifest.

$ okteto deploy

If there are pending changes in the images defined in your Okteto Manifest, okteto deploy automatically builds and pushes all them. This way, okteto deploy enforce all your local changes are pushed to your Development Environment.

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 Okteto Manifest is located. This means, that if the Okteto Manifest is at any subfolder, the command will use the context of the subfolder where the Okteto Manifest is defined.

Options

Options	Type	Description	Default
--dependencies	bool	Force deployment of repositories in the `dependencies` section	`false`
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
--name	string	The name of the Development Environment	The repo/folder name
-n, --namespace	string	Overwrite the current Okteto Namespace
--no-bash	bool	Execute the command using the container's default shell instead of bash	`false`
--no-build	bool	Skips the re-build of images in the `build` section	`false`
--remote	bool	Run the deploy commands using Remote Execution	`false`
-t, --timeout	duration	The duration to wait until all pods are healthy. Requires `--wait`. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h	5m0s
-v, --var	list	Set a variable for the deploy commands (can be set more than once)
-w, --wait	bool	Wait until the deployment finishes and pods are healthy	`false`

destroy
Platform

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

The okteto destroy command will only destroy resources matching the specified Development Environment name. By default, this is the name of the folder, but you can specify the name in the Okteto Manifest, or with the --name flag. In a monorepo scenario, where you might have several Okteto Manifests, you need to specify the correct Okteto Manifest to destroy the specific Development Environment. This ensures that the appropriate destroy commands, as defined in your Okteto Manifest, are executed within a particular scope.

This way, executing the okteto destroy command on one Development Environment will not delete the other. For example, if you have two Development Environments, dev1 and dev2, and you run okteto destroy for dev1, it will only destroy the resources for dev1 and leave dev2 intact.

You can use okteto destroy --all to delete all Development Environments in an Okteto Namespace.

Options

Options	Type	Description	Default
--all	bool	Destroy all Development Environments, excluding resources annotated with `dev.okteto.com/policy: keep`	`false`
-d, --dependencies	bool	Force destroy repositories in the `dependencies` section	`false`
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
--force-destroy	bool	Forces the Development Environment to be destroyed even if there is an error executing the custom destroy commands defined in the Okteto Manifest	`false`
--name	string	The name of the Development Environment	The repo/folder name
-n, --namespace	string	Overwrite the current Okteto Namespace
--no-bash	bool	Execute the command using the container's default shell instead of bash	`false`
--remote	bool	Run the destroy commands using Remote Execution	`false`
-v, --volumes	bool	Destroy the persistent volumes created by the Development Environment	`false`

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

doctor
PlatformOpen-Source

Generate a doctor file with all the information relevant for troubleshooting an issue. Use it when filing an issue or asking the Okteto community for help.

$ okteto doctor [devContainer]

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 following command flags are available:

Options	Type	Description	Default
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
-n, --namespace	string	Overwrite the current Okteto Namespace

down
PlatformOpen-Source

Deactivate your Development Container, stops the file synchronization service, and restores your previous deployment configuration.

$ okteto down [devContainer]

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

Options	Type	Description	Default
-A, --all	bool	Deactivate all running Development Containers	`false`
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
-n, --namespace	string	Overwrite the current Okteto Namespace
-v, --volumes	bool	Remove persistent volumes where your local folder is synced on remote	`false`

endpoints
Platform

List the public endpoints of your Development Environment.

$ okteto endpoints

Options	Type	Description
-f, --file	string	The path to the Okteto Manifest
--name	string	The name of the Development Environment
-n, --namespace	string	Overwrite the current Okteto Namespace
-o, --output	string	Output format. One of: ['json', 'md']

exec
PlatformOpen-Source

The exec command allows you to execute a COMMAND inside your Development Container, created by an okteto up session which is already running. It is important to note that okteto exec can only be used with a container that is in development mode. If there is no active Development Container corresponding to the current folder, the command will fail.

If only one Development Container is running, okteto exec will automatically connect to it. If multiple Development Containers are activated, you'll be presented with a selector to choose which one you want to connect to.

$ okteto exec [devContainer] -- COMMAND

Make sure to run the exec command from the same directory where you ran okteto up.

Options	Type	Description	Default
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
-n, --namespace	string	Overwrite the current Okteto Namespace

help
PlatformOpen-Source

Displays the full help.

$ okteto help

kubeconfig
PlatformOpen-Source

Download credentials for the Kubernetes cluster selected via okteto context.

$ okteto kubeconfig

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

logs
Platform

Fetch the logs of your Development Environment.

$ okteto logs [serviceName]

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

Options	Type	Description	Default
-a, --all	bool	Fetch logs from the whole namespace	`false`
-e, --exclude	string	Exclude by container name (regular expression)
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
--name	string	The name of the Development Environment	The repo/folder name
-n, --namespace	string	Overwrite the current Okteto Namespace
-s, --since	duration	Return logs newer than a relative duration like 5s, 2m, or 3h	48h0m0s
--tail	int	The number of lines from the end of the logs to show	100
-t, --timestamps	bool	Print timestamps	`false`

namespace
Platform

Configure the default namespace of the Okteto Context.

$ okteto namespace

tip

okteto ns is an alias of 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 @ okteto.example.com

Options	Type	Description	Default
--personal	bool	Load personal namespace	`false`

create

Create an Okteto Namespace. By default the command will switch to the new namespace, add --use=false to create the namespace, and it will keep the current namespace active.

$ okteto namespace create test-cindy

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

delete

Delete an Okteto Namespace. If the Okteto Manifest deployed in the Okteto Namespace include destroy commands, they will be executed as part of this command. By default, it deletes the default namespace in the Okteto Context.

$ okteto namespace delete test-cindy

 ✓  Namespace 'test-cindy' deleted

list

List your Okteto Namespaces.

$ okteto namespace list

Namespace       Status
demos-cindy     Active
cindy *         Active

use

Configure the default namespace of the Okteto Context. okteto namespace use is an alias of okteto namespace.

sleep

Sleeps an Okteto Namespace. By default, it sleeps the default namespace in the Okteto Context.

$ okteto namespace sleep [name]

i  Using test-cindy @ okteto.example.com as context
✓  Namespace 'test-cindy' is sleeping

If you'd like to sleep an Okteto Namespace other than the default one, you can provide its name as an argument to the command.

wake

Wakes an Okteto Namespace. By default, it wakes the default namespace in the Okteto Context.

$ okteto namespace wake [name]

i  Using test-cindy @ okteto.example.com as context
✓  Namespace 'test-cindy' is awake now

If you'd like to wake an Okteto Namespace other than the default one, you can provide its name as an argument to the command.

pipeline
Platform

Development Environments management commands.

$  okteto pipeline [command]

Available subcommands:

deploy

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

$ okteto pipeline deploy

Options

Options	Type	Description	Default
-b, --branch	string	The branch to deploy	Your current branch
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
--label	list	Tag and organize Development Environments using labels (multiple --label flags accepted)
--name	string	The name of the Development Environment	The repo/folder name
-n, --namespace	string	Overwrite the current Okteto Namespace
-r, --repository	string	The HTTPS url of the repository to deploy (e.g. https://github.com/okteto/movies)	Your current repository
--reuse-params	bool	If the Development Environment exists, reuse same parameters to redeploy
--skip-if-exists	bool	Skip the deployment if the Development Environment already exists in the Okteto Namespace	`false`
-t, --timeout	duration	The duration to wait for the deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h	5m0s
-v, --var	list	Set a variable to be injected in the deploy commands (can be set more than once)
-w, --wait	bool	Wait until the deployment finishes	`true`

destroy

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

$ okteto pipeline destroy

Options

Options	Type	Description	Default
--name	string	The name of the Development Environment	The repo/folder name
-n, --namespace	string	Overwrite the current Okteto Namespace
-t, --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	5m0s
-v, --volumes	bool	Destroy the persistent volumes created by the Development Environment	`false`
-w, --wait	bool	Wait until the Development Environment is destroyed	`true`

list

List all your Development Environments in the current Okteto Namespace.

$ okteto pipeline list

Run okteto pipeline list to get the status and info of your Development Environments.

Options	Type	Description	Default
--label	list	Tag and organize Development Environments using labels (multiple --label flags accepted)
-n, --namespace	string	Overwrite the current Okteto Namespace
-o, --output	string	Output format. One of: ['json', 'yaml']	`json`

preview
Platform

Preview environment management commands.

$ okteto preview [command]

deploy

Deploy a Preview Environment.

$ okteto preview deploy [name]

Run okteto preview deploy to automatically deploy a Preview Environment for your branch.

Options	Type	Description	Default
-b, --branch	string	The branch to deploy	Your current branch
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
--label	list	Tag and organize Preview Environments using labels (multiple --label flags accepted)
--repository	string	The url of the repository to deploy (e.g. https://github.com/okteto/movies)	Your current repo
-s, --scope	string	The scope of Preview Environment to create: `personal` or `global`. A personal Preview Environment can only be accessed by its creator, while in a global Preview Environment all cluster users can access it.	`global`
--sourceUrl	string	The HTTPS url of the pull/merge request to deploy.
-t, --timeout	duration	The duration to wait for the deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h	5m0s
-v, --var	list	Set a variable to be injected in the deploy commands (can be set more than once)
-w, --wait	bool	Wait until the deployment finishes	`true`

destroy

Destroy a Preview Environment.

$ okteto preview destroy [name]

Run okteto preview destroy to destroy a Preview Environment by name.

If the Okteto Manifest includes destroy commands, they will be executed as part of this command.

Options	Type	Description	Default
-w, --wait	bool	Wait until the Preview Environment destruction finishes	`true`

endpoints

List the endpoints of a Preview Environment.

$ okteto preview endpoints [name]

Options	Type	Description	Default
-o, --output	string	Output format. One of: [`json`, `md`]	`json`

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

list

List all your Preview Environments.

$ okteto preview list

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

Options	Type	Description	Default
--label	list	Tag and organize Preview Environments using labels (multiple --label flags accepted)
-n, --namespace	string	Overwrite the current Okteto Namespace
-o, --output	string	Output format. One of: [`json`, `yaml`]	`json`

sleep

Sleep an Preview Environment. Only users with admin access or who own the Preview Environment can take this action.

$ okteto preview sleep [name]

wake

Wake a Preview Environment. You must provide the name of a Preview Environment as an argument for this command.

$ okteto namespace wake [name]

restart
PlatformOpen-Source

Restarts the containers corresponding to the services section for a given Development Container. This is useful to reload configurations that cannot be hot-reloaded.

$ okteto restart [devContainer]

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

Options	Type	Description	Default
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
-n, --namespace	string	Overwrite the current Okteto Namespace

status
PlatformOpen-Source

Status of the file synchronization process for a given Development Container.

$ okteto status [devContainer] --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	Default
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
--info	bool	Show syncthing links for troubleshooting the synchronization service
-n, --namespace	string	Overwrite the current Okteto Namespace
-w, --watch	bool	Watch for changes

test
Platform

Run tests using Remote Execution.

$ okteto test [testContainerName]

Since tests run inside the cluster, all internal endpoints are available inside the test execution. For example, if you deployed an api service on port 8080 it will be accessible at: http://api.${OKTETO_NAMESPACE}:8080. Dynamic endpoints are also available within the test commands.

Options	Type	Description	Default
--deploy	bool	Force execution of the commands in the `deploy` section	`false`
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
-n, --namespace	string	Overwrite the current Okteto Namespace
--name	string	The name of the Development Environment	The repo/folder name
--no-cache	bool	By default, the `caches` of a Test Container are reused between executions	`false`
-t, --timeout	duration	The duration to wait for the Test Container to run. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h	5m0s
-v, --var	list	Set a variable to be injected in the test commands (can be set more than once)

up
PlatformOpen-Source

Activate a Development Container.

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

$ okteto up [devContainer]

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 Container inherits the original deployment manifest definition. Therefore, the Development Container 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	Default
-d, --deploy	bool	Force the redeployment of your Development Environment	`false`
-e, --env	list	Set environment variable in the Development Container
-f, --file	string	The path to the Okteto Manifest	`okteto.yml`
-n, --namespace	string	Overwrite the current Okteto Namespace
-r, --remote	int	Exposes the SSH server in a given port
--reset	bool	Resets the file synchronization service. Use it if the file synchronization service stops working	`false`

You can also overwrite the start command in your Development Container with the syntax okteto up -- COMMAND [args...].

version
PlatformOpen-Source

Show the current installed Okteto CLI binary version

$ okteto version

Available subcommands:

update

Show information about how to update the Okteto CLI binary.

$ okteto version update

You can update okteto with the following:

# Using installation script:
curl https://get.okteto.com -sSfL | sh

# Using brew:
brew upgrade okteto

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://okteto.example.com cindy

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​

Global Flags​

Available commands​

analyticsPlatformOpen-Source​

buildPlatform​

contextPlatformOpen-Source​

delete​

list​

show​

use​

deployPlatform​

Options​

destroyPlatform​

Options​

doctorPlatformOpen-Source​

downPlatformOpen-Source​

endpointsPlatform​

execPlatformOpen-Source​

helpPlatformOpen-Source​

kubeconfigPlatformOpen-Source​

logsPlatform​

namespacePlatform​

create​

delete​

list​

use​

sleep​

wake​

pipelinePlatform​

deploy​

Options​

destroy​

Options​

list​

previewPlatform​

deploy​

destroy​

endpoints​

list​

sleep​

wake​

restartPlatformOpen-Source​

statusPlatformOpen-Source​

testPlatform​

upPlatformOpen-Source​

versionPlatformOpen-Source​

update​

Troubleshooting​

Kubernetes authentication​

Synopsis

Global Flags

Available commands

analytics
PlatformOpen-Source

build
Platform

context
PlatformOpen-Source

delete

list

show

use

deploy
Platform

Options

destroy
Platform

Options

doctor
PlatformOpen-Source

down
PlatformOpen-Source

endpoints
Platform

exec
PlatformOpen-Source

help
PlatformOpen-Source

kubeconfig
PlatformOpen-Source

logs
Platform

namespace
Platform

create

delete

list

use

sleep

wake

pipeline
Platform

deploy

Options

destroy

Options

list

preview
Platform

deploy

destroy

endpoints

list

sleep

wake

restart
PlatformOpen-Source

status
PlatformOpen-Source

test
Platform

up
PlatformOpen-Source

version
PlatformOpen-Source

update

Troubleshooting

Kubernetes authentication