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]

By default, images are built using the Okteto Build Service. Set the variable BUILDKIT_HOST if you want to use your own BuildKit instance.

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

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 Enterprise instance by specifying a URL.

$ 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)
--filename(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)

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. By default, images are built using the Okteto Build Service. Set the variable BUILDKIT_HOST if you want to use your own BuildKit instance.

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

When you run okteto stack deploy, okteto will create the services defined in your Stack manifest.

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(string)Path to the stack manifest file (default "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

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(string)Path to the stack manifest file (default "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)

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 will swap the specified deployment with your development container. A development container is a copy of your existing kubernetes deployment with the following improvements:

  • Update your application containers with the docker image specified in your okteto manifest
  • Create a bidirectional file synchronization service to keep your changes up to date between your local filesystem and your development container
  • Automatic local and remote port forwarding using SSH, so you can access your cluster services via localhost or connect a remote debugger

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