Link Search Menu Expand Document

Command line tool (CLI)

  1. Command line tool (CLI)
    1. Syntax
  2. Actions
    1. up
    2. run
    3. bridge
    4. unbridge
    5. reflect
    6. down
    7. list
    8. check
    9. version
    10. status
    11. telemetry

This reference is for version 1.0.x


Use the following syntax to run gefyra commands from your terminal:

gefyra [-h] [-d] [action] [arguments]

where action and arguments are:

  • action: specifies the operation that you want to perform, for example up or bridge
  • arguments: specifies the required and optional arguments for a specific action, for example -n or --namespace

Global flags are:

  • -h, --help: show help message and exit
  • -d, --debug: add debug output for each action


The CLI allows to run the following available actions.


Brings up a local development infrastructure. Gefyra pulls the active kubectl connection and installs Operator to the connected cluster. Gefyra waits for Operator to become ready. In the last step, Gefyra rolls out the local Docker network and traffic tunnel endpoint. Import In some scenarios firewalls may be blocking port 31280. Make sure it is reachable from your machine.


gefyra up


-H, --hostHost address for Gefyra to connect to
Important: Be sure to allow your firewall for this IP and port to let traffic pass through
-P, --portPort for Gefyra to connect to
Important: Default is 31280.
-M, --minikubeLet Gefyra automatically find out the connection parameters for a local Minikube cluster
Important: This cannot be used together with the --host option
-o, --operatorThe full image path (including tag) for the Operator image (e.g. 
-s, --stowawayThe full image path (including tag) for the Stowaway image (e.g. 
-c, --carrierThe full image path (including tag) for the Carrier image (e.g. 
-a, --cargoThe full image path (including tag) for the Cargo image (e.g. 
-r, --registryThe base url for registry to pull images from (e.g., the full image paths will be constructed using the name and the tag of the release 
--kubeconfigThe path to kubeconfig file to the Kubernetes cluster (default is global kubeconfig) 
--contextThe context name from kubeconfig (default is active global context) 
--wireguard-mtuThe MTU value for the local Wireguard endpoint (default: 1340) 


Run a new app container image in Gefyra’s development infrastructure. Any Docker image is supported. It is required to assign a name to the container instance for further reference.


gefyra run -i pyserver -N mypyserver -n default


-i, --imageThe Docker image to run in Gefyra (required)
-N, --nameThe name of the container running in Gefyra
-n, --namespaceThe Kubernetes namespace for this container to run in (default: default)
-c, --commandThe command for this container to run in Gefyra
--exposeAdd port mapping in form of <ip>:<host_port>:<container_port>
Important: This works just as docker run --expose (see: Docker reference)
--rmAutomatically remove the container when it exits or when it is killed
--envSet or override environment variables in the form ENV=value, allowed multiple times
--env-fromCopy the environment from the container in the notation <workload_type>/<workload_name>/<container>. container is optional.
Example: deploy/some-deployment or pod/pod-name-1dd1/my-container.
-v, --volumeBind mount a volume into the container in notation src:dest, allowed multiple times


Intercept the traffic to a container that’s running in the Kubernetes cluster and send it to the development container. You can watch active bridges with kubectl -n gefyra get ireq (InterceptRequests). The container is the cluster will be replaced by Gefyra’s proxy component Carrier. Carrier redirects all requests from the intercepted container (running in a Pod) to the local development container. During the bridge operation Carrier can fake-serve httpGet probes. There is one bridge for each Pod/container combination if a Deployment or Statefulset is selected with more than one Pod.


gefyra bridge -N mypyserver --target deploy/hello-nginxdemo/hello-nginx --port 80:8000 -n default


-N, --nameThe name of the container running in Gefyra (started with run) receiving the traffic (required)
-p, --portThe port mapping from source to target in the form <source>:<target>, allowed multiple times (required)
-n, --namespaceThe Kubernetes namespace for this container to run in (default: default)
-P, --no-probe-handlingMake Carrier to not handle probes during the bridge operation
--targetTarget to bridge in the notation of <type>/<workload_name>/<container>
Important: <type> can be one of {pod, po, pods, deploy, deployment, deployments, statefulset, sts, statefulsets}, <workload_name> is the name of the resource to bridge and <container> is the name of the container within the resource.


Remove active traffic intercepts and reset the cluster to its original state.


gefyra unbridge -N mypybridge


-N, --nameThe name of the bridge to be removed
-A, --allRemove all bridges at once


Combines run and bridge commands. It starts a new container in Gefyra and bridges the traffic to it. reflect takes a workload as argument and mirrors the given workload on the local machine. It is possible to overwrite several aspects of the workload, e.g. the image, the command or the environment variables.


gefyra reflect


-w, --workloadThe workload to be mirrored on the local machine. 
-e, --exposeIf set use ports from Kubernetes resource to expose the container to the host. 
-i, --imageOverwrite the container’s image. Useful if there is a development version of your image. 
-v, --volumeAttach a volume to the container. Useful to mount code from host system to the container. 
-p, --portOverwrite ports which should be exposed from the container to the host. 
-b, --bridgeBridge workload immediately when container has started. 
-c, --commandOverwrite command of container. 
-n, --namespaceNamespace of the workload. Default to default. 
--envAdd environment variable to container e.g. --env KUBE=2 


Remove Gefyra’s development infrastructure, including active bridges and all cluster components. The local Docker network will be removed as well.


gefyra down

No arguments available.


List running containers and active bridges. You can select either --bridges or --containers to display.


gefyra list --bridges


--bridgesList only bridges
--containersList only local development containers


Check local system dependencies, such as Docker and Kubernetes.


gefyra check

No arguments available.


Display the current version and exit.


gefyra version

No arguments available.


Display the status of Gefyra on the local machine and the cluster.


gefyra status

No arguments available.


Gefyra anonymously tracks its usage by collecting telemetry data. Telemetry is enabled by default.


gefyra telemetry --on


--offTurn off telemetry
--onTurn on telemetry