Skip to main content
Version: 1.26

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

OptionsTypeDescriptionDefault
--helpboolShow help info
-l, --log-leveldebug, info, warn, errorAmount of information outputwarm
--log-outputtty, plain, jsonOutput format for logstty

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]
OptionsDescription
-d, --disableDisable 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:

OptionsTypeDescriptionDefault
-f, --filestringThe path to the Okteto Manifestokteto.yml
-n, --namespacestringOverwrite the current Okteto Namespace
--no-cacheboolDo not use cache when building the imagefalse
--progressstringShow plain/tty build outputtty

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):

OptionsTypeDescriptionDefault
--build-arglistSet build-time variables (optional)
--cache-fromlistList of cache source images (optional)
--export-cachestringImage tag for exported cache when build (optional)
--platformstringSpecify which platform to build the container image for (optional)
--secretlistSecret files exposed to the build. Format: id=mysecret,src=/local/secret
-t, --tagstringTag name to be pushed (optional)
--targetstringTarget 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
OptionsTypeDescriptionDefault
--insecure-skip-tls-verifyboolSkip validation of server's certificatesfalse
-n, --namespacestringOverwrite the current Okteto Namespace
--tokenstringAPI 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 -
OptionsTypeDescriptionDefault
-o, --outputstringOutput format. One of: json, yamljson

show

Print the current Okteto Context.

$ okteto context show
OptionsTypeDescriptionDefault
--include-tokenboolInclude the token in the outputfalse
-o, --outputstringOutput format. One of: json, yamljson
{
"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
OptionsTypeDescriptionDefault
--dependenciesboolForce deployment of repositories in the dependencies sectionfalse
-f, --filestringThe path to the Okteto Manifestokteto.yml
--namestringThe name of the Development EnvironmentThe repo/folder name
-n, --namespacestringOverwrite the current Okteto Namespace
--no-bashboolExecute the command using the container's default shell instead of bashfalse
--no-buildboolSkips the re-build of images in the build sectionfalse
--remoteboolRun the deploy commands using Remote Executionfalse
-t, --timeoutdurationThe duration to wait until all pods are healthy. Requires --wait. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h5m0s
-v, --varlistSet a variable for the deploy commands (can be set more than once)
-w, --waitboolWait until the deployment finishes and pods are healthyfalse

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
OptionsTypeDescriptionDefault
--allboolDestroy all Development Environments, excluding resources annotated with dev.okteto.com/policy: keepfalse
-d, --dependenciesboolForce destroy repositories in the dependencies sectionfalse
-f, --filestringThe path to the Okteto Manifestokteto.yml
--force-destroyboolForces the Development Environment to be destroyed even if there is an error executing the custom destroy commands defined in the Okteto Manifestfalse
--namestringThe name of the Development EnvironmentThe repo/folder name
-n, --namespacestringOverwrite the current Okteto Namespace
--no-bashboolExecute the command using the container's default shell instead of bashfalse
--remoteboolRun the destroy commands using Remote Executionfalse
-v, --volumesboolDestroy the persistent volumes created by the Development Environmentfalse

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:

OptionsTypeDescriptionDefault
-f, --filestringThe path to the Okteto Manifestokteto.yml
-n, --namespacestringOverwrite 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.

OptionsTypeDescriptionDefault
-A, --allboolDeactivate all running Development Containersfalse
-f, --filestringThe path to the Okteto Manifestokteto.yml
-n, --namespacestringOverwrite the current Okteto Namespace
-v, --volumesboolRemove persistent volumes where your local folder is synced on remotefalse

endpoints
Platform

List the public endpoints of your Development Environment.

$ okteto endpoints
OptionsTypeDescription
-f, --filestringThe path to the Okteto Manifest
--namestringThe name of the Development Environment
-n, --namespacestringOverwrite the current Okteto Namespace
-o, --outputstringOutput 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.

OptionsTypeDescriptionDefault
-f, --filestringThe path to the Okteto Manifestokteto.yml
-n, --namespacestringOverwrite 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.

OptionsTypeDescriptionDefault
-a, --allboolFetch logs from the whole namespacefalse
-e, --excludestringExclude by container name (regular expression)
-f, --filestringThe path to the Okteto Manifestokteto.yml
--namestringThe name of the Development EnvironmentThe repo/folder name
-n, --namespacestringOverwrite the current Okteto Namespace
-s, --sincedurationReturn logs newer than a relative duration like 5s, 2m, or 3h48h0m0s
--tailintThe number of lines from the end of the logs to show100
-t, --timestampsboolPrint timestampsfalse

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
OptionsTypeDescriptionDefault
--personalboolLoad personal namespacefalse

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
OptionsTypeDescriptionDefault
-b, --branchstringThe branch to deployYour current branch
-f, --filestringThe path to the Okteto Manifestokteto.yml
--labellistTag and organize Development Environments using labels (multiple --label flags accepted)
--namestringThe name of the Development EnvironmentThe repo/folder name
-n, --namespacestringOverwrite the current Okteto Namespace
-r, --repositorystringThe HTTPS url of the repository to deploy (e.g. https://github.com/okteto/movies)Your current repository
--reuse-paramsboolIf the Development Environment exists, reuse same parameters to redeploy
--skip-if-existsboolSkip the deployment if the Development Environment already exists in the Okteto Namespacefalse
-t, --timeoutdurationThe duration to wait for the deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h5m0s
-v, --varlistSet a variable to be injected in the deploy commands (can be set more than once)
-w, --waitboolWait until the deployment finishestrue

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
OptionsTypeDescriptionDefault
--namestringThe name of the Development EnvironmentThe repo/folder name
-n, --namespacestringOverwrite the current Okteto Namespace
-t, --timeoutstringThe duration to wait for the Development Environment to be destroyed. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h5m0s
-v, --volumesboolDestroy the persistent volumes created by the Development Environmentfalse
-w, --waitboolWait until the Development Environment is destroyedtrue

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.

OptionsTypeDescriptionDefault
--labellistTag and organize Development Environments using labels (multiple --label flags accepted)
-n, --namespacestringOverwrite the current Okteto Namespace
-o, --outputstringOutput 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.

OptionsTypeDescriptionDefault
-b, --branchstringThe branch to deployYour current branch
-f, --filestringThe path to the Okteto Manifestokteto.yml
--labellistTag and organize Preview Environments using labels (multiple --label flags accepted)
--repositorystringThe url of the repository to deploy (e.g. https://github.com/okteto/movies)Your current repo
-s, --scopestringThe 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 stringThe HTTPS url of the pull/merge request to deploy.
-t, --timeoutdurationThe duration to wait for the deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h5m0s
-v, --varlistSet a variable to be injected in the deploy commands (can be set more than once)
-w, --waitboolWait until the deployment finishestrue

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.

OptionsTypeDescriptionDefault
-w, --waitboolWait until the Preview Environment destruction finishestrue

endpoints

List the endpoints of a Preview Environment.

$ okteto preview endpoints [name]
OptionsTypeDescriptionDefault
-o, --outputstringOutput 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.

OptionsTypeDescriptionDefault
--labellistTag and organize Preview Environments using labels (multiple --label flags accepted)
-n, --namespacestringOverwrite the current Okteto Namespace
-o, --outputstringOutput 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]

More on sleeping resources here.

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.

OptionsTypeDescriptionDefault
-f, --filestringThe path to the Okteto Manifestokteto.yml
-n, --namespacestringOverwrite 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.

OptionsTypeDescriptionDefault
-f, --filestringThe path to the Okteto Manifestokteto.yml
--infoboolShow syncthing links for troubleshooting the synchronization service
-n, --namespacestringOverwrite the current Okteto Namespace
-w, --watchboolWatch 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.

OptionsTypeDescriptionDefault
--deployboolForce execution of the commands in the deploy sectionfalse
-f, --filestringThe path to the Okteto Manifestokteto.yml
-n, --namespacestringOverwrite the current Okteto Namespace
--namestringThe name of the Development EnvironmentThe repo/folder name
--no-cacheboolBy default, the caches of a Test Container are reused between executionsfalse
-t, --timeoutdurationThe duration to wait for the Test Container to run. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h5m0s
-v, --varlistSet 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.

OptionsTypeDescriptionDefault
-d, --deployboolForce the redeployment of your Development Environmentfalse
-e, --envlistSet environment variable in the Development Container
-f, --filestringThe path to the Okteto Manifestokteto.yml
-n, --namespacestringOverwrite the current Okteto Namespace
-r, --remoteintExposes the SSH server in a given port
--resetboolResets the file synchronization service. Use it if the file synchronization service stops workingfalse

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.