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

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 the all 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 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)
--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 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)

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 on 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/.

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, stored 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)
--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)

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)

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 configuration 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 againts 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 lost. 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)
--deploy(bool)Don't ask for confirmation to create dev environments if deployment doesn't exist
--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