Skip to main content

Okteto CLI Reference

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

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.

OptionsValues
--logleveldebug, info, warn, error

The amount of information outputted (defaults to warn).

Available commands

analytics

Enable / Disable analytics collection. Analytics are enabled by default

$ okteto analytics [parameters]
OptionsDescription
--disableDisables 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:

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

build

Build an image from a Dockerfile and push it to a registry:

$ okteto build [PATH]

If your okteto context points to Okteto Cloud or an Okteto Enterprise URL, images are built using the Okteto Build Service. Otherwise, images are built using your local Docker daemon.

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

OptionsTypeDescription
--file(string)The path to the Dockerfile file
--tag(string)Name and optionally a tag in the name:tag format (it is automatically pushed)
--target(string)Set the target build stage to build
--no-cache(bool)Do not use cache when building the image (default: false)
--cache-from(string)Cache source image (optional)
--build-arg(list)Set build-time variables
--secret(list)Secret files exposed to the build. Format: id=mysecret,src=/local/secret

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

Available subcommands:

create

Add a context.

You need to specify an Okteto URL. For example, run:

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

to configure your context to access Okteto Cloud.

Your browser will ask for your authentication to retrieve your API token.

If you need to automate authentication or if you don't want to use browser-based authentication, use the --token parameter:

$ okteto context create https://cloud.okteto.com --token ${OKTETO_TOKEN}

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
}

update-kubeconfig

Download kubectl credentials for the current context.

$ okteto context update-kubeconfig
i Updated kubernetes context 'cloud_okteto_com/cindy' in '/Users/cindy/.kube/config'

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

use-namespace

Set the namespace of the current context.

$ okteto context use-namespace cindy
i Using cindy @ cloud.okteto.com as context

doctor

Generates a doctor file with the okteto logs:

$ okteto doctor

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 in the #okteto channel in the Kubernetes community Slack when asking for assistance.

down

Deactivates your development container, stops the file synchronization service, and restores your previous deployment configuration

$ okteto down

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

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

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 COMMAND

For more complex commands we recommend using a double dash (--) before the command parameter.

okteto exec -- COMMAND

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

OptionsTypeDescription
--file(string)The path to the manifest file (default "okteto.yml")
--namespace(string)The Kubernetes namespace to use (defaults to the current kube config namespace)
--context(string)The Kubernetes context to use (defaults to the current kube config context)

help

Displays the full help

$ okteto help

init

Automatically generates the okteto manifest file and a .stignore file. Okteto will scan the current folder and will generate a default manifest file based on your programming language and platform.

$ okteto init
OptionsTypeDescription
--file(string)The path to the manifest file to create (default "okteto.yml")

login

Log into Okteto, and download your API token and certificates required to interact with the Okteto Build Service. It defaults to Okteto Cloud, but you can specify your own Okteto URL by specifying a URL argument.

$ okteto login [URL]
OptionsTypeDescription
--token(string)Your Okteto API token. Use this when scripting or if you don't want to use browser-based authentication.

When you run okteto login, an account will be created for your own URL if it's the first time you log 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:

namespace

Downloads k8s credentials for a Kubernetes namespace. It defaults to your personal namespace.

$ okteto namespace [namespace]

When you run okteto namespace, okteto will download the Kubernetes credentials for the namespace you specified, store them in your kubeconfig file, and set the current context to it.

pipeline

Pipeline management commands

$ okteto pipeline [command]

Available subcommands:

deploy

Deploy your okteto pipeline

$ okteto pipeline deploy

Run okteto pipeline deploy to automatically start an Okteto pipeline for your repository. This is equivalent to clicking the deploy button on the Okteto UI and selecting the Deploy from Git Repository option.

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

Options
OptionsTypeDescription
--branch(string)The branch to deploy (defaults to the main branch)
--file(string)The location of the pipeline file. 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

Destroy your okteto pipeline

$ okteto pipeline destroy

Run okteto pipeline destroy to automatically destroy an existing pipeline in Okteto. This is equivalent to clicking the destroy button on the Okteto UI.

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

Options
OptionsTypeDescription
--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.

$ 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 application.

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

OptionsTypeDescription
--branch(string)The branch to deploy (defaults to your current branch)
--file(string)The location of the pipeline file. 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 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

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.

endpoints

List the endpoints of a preview environment.

$ okteto preview endpoints [name]

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

OptionsTypeDescription
--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.

push

Build, push, and redeploy your source code to Kubernetes

$ okteto push

okteto push builds a new docker image, pushes it to the registry, and redeploys your containers. If you have an active development container created by okteto up, it is also deactivated as part of the push operation.

If your okteto context points to Okteto Cloud or an Okteto Enterprise URL, images are built using the Okteto Build Service. Otherwise, images are built using your local Docker daemon.

OptionsTypeDescription
--file(string)The path to the okteto manifest file. The manifest file indicates the deployment to push (default "okteto.yml")
--tag(string)The name of the image tag to build, push, and redeploy (defaults to the original container image but using the tag okteto)
--namespace(string)The Kubernetes namespace to use (defaults to the current kube config namespace)
--context(string)The Kubernetes context to use (defaults to the current kube config context)
--no-cache(bool)Do not use cache when building the image

restart

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

$ okteto restart

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

OptionsTypeDescription
--file(string)The path to the manifest file (default "okteto.yml")
--namespace(string)The Kubernetes namespace to use (defaults to the current kube config namespace)
--context(string)The Kubernetes context to use (defaults to the current kube config context)

stack

Stack management commands

$ okteto stack [command]

Available subcommands:

deploy

Deploy your stack

$ okteto stack deploy

By default okteto stack deploy will create all the services defined in your Stack manifest. If you only want to deploy a specific set of services, pass their names as arguments.

$ okteto stack deploy [SERVICE...]

Once your Stack is deployed, you can run okteto up against any of the Stack services as you do for any other Kubernetes deployment.

Options
OptionsTypeDescription
--build(bool)Build images before starting any service (default false)
--file(list)Path to the stack manifest files (defaults to okteto-stack.yml or .okteto/okteto-stack.yml)
--name(string)Overwrites the stack name
--namespace(string)The Kubernetes namespace to use (defaults to the current kube config namespace)
--context(string)The Kubernetes context to use (defaults to the current kube config context)
--no-cache(bool)Do not use cache when building images
--wait(bool)Wait until a minimum number of containers are in a ready state for every service

By default, Okteto reads two files, an okteto-stack.yml and an optional okteto-stack.override.yml file. If both files exist, or if --file refers to a list of stack manifests, stack manifests are merged. A manifest merge means any field defined in the second stack manifest replaces the value in the first stack manifest.

If your okteto context points to Okteto Cloud or an Okteto Enterprise URL, images are built using the Okteto Build Service. Otherwise, images are built using your local Docker daemon.

destroy

Destroy your stack

$ okteto stack destroy

When you run okteto stack destroy, okteto will delete the services defined in your Stack manifest.

Persistent volumes created by your stack are not deleted to avoid accidental data loss. If you want to delete them, you can do it by executing kubectl delete pvc $PVC_NAME.

Options
OptionsTypeDescription
--file(list)Path to the stack manifest files (defaults to okteto-stack.yml or .okteto/okteto-stack.yml)
--name(string)Overwrites the stack name
--namespace(string)The Kubernetes namespace to use (defaults to the current kube config namespace)
--context(string)The Kubernetes context to use (defaults to the current kube config context)
--volumes(bool)Destroy the persistent volumes created by the stack (defaults to false)

By default, Okteto reads two files, an okteto-stack.yml and an optional okteto-stack.override.yml file. If both files exist, or if --file refers to a list of stack manifests, stack manifests are merged. A manifest merge means any field defined in the second manifest replaces the value in the first manifest.

status

Status of the file synchronization process:

$ okteto status --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.

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

up

Activate your development container

$ okteto up

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.

OptionsTypeDescription
--file(string)The path to the manifest file (default "okteto.yml")
--namespace(string)The Kubernetes namespace to use (defaults to the current kube config namespace)
--context(string)The Kubernetes context to use (defaults to the current kube config context)
--build(bool)Build on-the-fly the dev image using the info provided by the 'build' okteto manifest field
--pull(bool)Sets the imagePullPolicy to Always and forces the recreation of the dev environments
--reset(bool)Resets the file synchronization service. Use it if the file synchronization service stops working.

version

Displays the current installed version

$ okteto version