Jina Command-Line Interface

usage: jina [-h] [-v] [-vf]
            {hello, executor, flow, ping ... 7 more choices} ...

Named Arguments

-v, --version

Show Jina version

-vf, --version-full

Show Jina and all dependencies’ versions

subcommands

Use %(prog)-8s [sub-command] –help to get detailed information about each sub-command.

To show all commands, run JINA_FULL_CLI=1 jina –help.

cli

Possible choices: hello, executor, flow, ping, gateway, hub, help, pea, pod, client, export-api

Sub-commands:

hello

Start hello world demos.

jina hello [-h] {fashion, chatbot, multimodal, fork} ...

subcommands

use %(prog)-8s [sub-command] –help to get detailed information about each sub-command

hello

Possible choices: fashion, chatbot, multimodal, fork

Sub-commands:

fashion

Run a fashion search demo

jina hello fashion [-h] [--workdir] [--download-proxy] [--index-data-url]
                   [--index-labels-url] [--query-data-url]
                   [--query-labels-url] [--num-query] [--top-k]
General arguments
--workdir

The workdir for hello-world demoall data, indices, shards and outputs will be saved there

Default: “34d69d98-e5e5-48e5-93d8-71f22cedb225”

--download-proxy

The proxy when downloading sample data

Index arguments
--index-data-url

The url of index data (should be in idx3-ubyte.gz format)

Default: “http://fashion-mnist.s3-website.eu-central-1.amazonaws.com/train-images-idx3-ubyte.gz

--index-labels-url

The url of index labels data (should be in idx3-ubyte.gz format)

Default: “http://fashion-mnist.s3-website.eu-central-1.amazonaws.com/train-labels-idx1-ubyte.gz

chatbot

Run a chatbot QA demo

jina hello chatbot [-h] [--workdir] [--download-proxy] [--index-data-url]
                   [--port-expose] [--replicas]
Named Arguments
--index-data-url

The url of index csv data

Default: “https://static.jina.ai/chatbot/dataset.csv

--port-expose

The port of the host exposed to the public

Default: 8080

--replicas

The number of replicas when index and query

Default: 2

General arguments
--workdir

The workdir for hello-world demoall data, indices, shards and outputs will be saved there

Default: “d32f9345-3b12-44ef-9472-804a50b2c3a1”

--download-proxy

The proxy when downloading sample data

multimodal

Run a multimodal search demo

jina hello multimodal [-h] [--workdir] [--download-proxy] [--index-data-url]
                      [--port-expose]
Named Arguments
--index-data-url

The url of index csv data

Default: “https://static.jina.ai/multimodal/people-img.zip

--port-expose

The port of the host exposed to the public

Default: 8080

General arguments
--workdir

The workdir for hello-world demoall data, indices, shards and outputs will be saved there

Default: “7c089e9f-0c5d-4f50-8b04-2cd3416527b3”

--download-proxy

The proxy when downloading sample data

fork

Fork a hello world project to a local directory.

jina hello fork [-h] {fashion, chatbot, multimodal} destination
Positional Arguments
project

Possible choices: fashion, chatbot, multimodal

The hello world project to fork

destination

The dest directory of the forked project. Note, it can not be an existing path.

executor

Start an Executor. Executor is how Jina processes Document.

jina executor [-h] [--name] [--workspace] [--log-config] [--quiet]
              [--quiet-error] [--static-routing-table] [--zmq-identity]
              [--port-ctrl] [--ctrl-with-ipc] [--timeout-ctrl] [--ssh-server]
              [--ssh-keyfile] [--ssh-password] [--uses]
              [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
              [--uses-metas [KEY: VALUE [KEY: VALUE ...]]]
              [--uses-requests [KEY: VALUE [KEY: VALUE ...]]]
              [--py-modules [PATH [PATH ...]]] [--port-in] [--port-out]
              [--hosts-in-connect [[...]]] [--host-in] [--host-out]
              [--socket-in {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
              [--socket-out {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
              [--memory-hwm]
              [--on-error-strategy {IGNORE, SKIP_HANDLE, THROW_EARLY}]
              [--native] [--runs-in-docker] [--entrypoint]
              [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]] [--pull-latest]
              [--volumes [DIR [DIR ...]]] [--gpus] [--host] [--port-jinad]
              [--quiet-remote-logs] [--upload-files [FILE [FILE ...]]]
              [--daemon] [--runtime-backend {THREAD, PROCESS}] [--runtime-cls]
              [--timeout-ready] [--env [KEY: VALUE [KEY: VALUE ...]]]
              [--expose-public] [--shards] [--replicas]
              [--install-requirements] [--force]

Essential arguments

--name

The name of this object.

This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - …

When not given, then the default naming strategy will apply.

--workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

--log-config

The YAML config of the logger used in this object.

Default: “/home/runner/work/jina/jina/jina/resources/logging.default.yml”

--quiet

If set, then no log will be emitted from this object.

Default: False

--quiet-error

If set, then exception stack information will not be added to the log

Default: False

--static-routing-table

Defines if the routing table should be pre computed by the Flow. In this case it is statically defined for each Pod and not send on every data request. Can not be used in combination with external pods

Default: False

ZMQRuntime arguments

--zmq-identity

The identity of a ZMQRuntime. It is used for unique socket identification towards other ZMQRuntimes.

--port-ctrl

The port for controlling the runtime, default a random port between [49152, 65535]

Default: 49403

--ctrl-with-ipc

If set, use ipc protocol for control socket

Default: False

--timeout-ctrl

The timeout in milliseconds of the control request, -1 for waiting forever

Default: 5000

--ssh-server

The SSH server through which the tunnel will be created, can actually be a fully specified [email protected]:port ssh url.

--ssh-keyfile

This specifies a key to be used in ssh login, default None. regular default ssh keys will be used without specifying this argument.

--ssh-password

The ssh password to the ssh server.

ZEDRuntime arguments

--uses

The config of the executor, it could be one of the followings: * an Executor YAML file (.yml, .yaml, .jaml) * a Jina Hub Executor (must start with jinahub:// or jinahub+docker://) * a docker image (must start with docker://) * the string literal of a YAML config (must start with ! or `jtype: `) * the string literal of a JSON config

When use it under Python, one can use the following values additionally: - a Python dict that represents the config - a text file stream has .read() interface

Default: “BaseExecutor”

--uses-with

Dictionary of keyword arguments that will override the with configuration in uses

--uses-metas

Dictionary of keyword arguments that will override the metas configuration in uses

--uses-requests

Dictionary of keyword arguments that will override the requests configuration in uses

--py-modules

The customized python modules need to be imported before loading the executor

Note that the recommended way is to only import a single module - a simple python file, if your executor can be defined in a single file, or an __init__.py file if you have multiple files, which should be structured as a python package. For more details, please see the Executor cookbook

--port-in

The port for input data, default a random port between [49152, 65535]

Default: 40069

--port-out

The port for output data, default a random port between [49152, 65535]

Default: 48985

--hosts-in-connect

The host address for input, by default it is 0.0.0.0

--host-in

The host address for input, by default it is 0.0.0.0

Default: “0.0.0.0”

--host-out

The host address for output, by default it is 0.0.0.0

Default: “0.0.0.0”

--socket-in

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for input port

Default: 0

--socket-out

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for output port

Default: 2

--memory-hwm

The memory high watermark of this pod in Gigabytes, pod will restart when this is reached. -1 means no restriction

Default: -1

--on-error-strategy

Possible choices: IGNORE, SKIP_HANDLE, THROW_EARLY

The skip strategy on exceptions.

  • IGNORE: Ignore it, keep running all Executors in the sequel flow

  • SKIP_HANDLE: Skip all Executors in the sequel, only pre_hook and post_hook are called

  • THROW_EARLY: Immediately throw the exception, the sequel flow will not be running at all

Note, IGNORE, SKIP_EXECUTOR and SKIP_HANDLE do not guarantee the success execution in the sequel flow. If something is wrong in the upstream, it is hard to carry this exception and moving forward without any side-effect.

Default: 0

--native

If set, only native Executors is allowed, and the Executor is always run inside ZEDRuntime.

Default: False

--runs-in-docker

Informs a Pea that runs in a container. Important to properly set networking information

Default: False

ContainerRuntime arguments

--entrypoint

The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective.

--docker-kwargs

Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘ container.

More details can be found in the Docker SDK docs: https://docker-py.readthedocs.io/en/stable/

--pull-latest

Pull the latest image before running

Default: False

--volumes

The path on the host to be mounted inside the container.

Note, - If separated by :, then the first part will be considered as the local host path and the second part is the path in the container system. - If no split provided, then the basename of that directory will be mounted into container’s root path, e.g. –volumes=”/user/test/my-workspace” will be mounted into /my-workspace inside the container. - All volumes are mounted with read-write mode.

--gpus

This argument allows dockerized Jina executor discover local gpu devices.

Note, - To access all gpus, use –gpus all. - To access multiple gpus, e.g. make use of 2 gpus, use –gpus 2. - To access specified gpus based on device id, use –gpus device=[YOUR-GPU-DEVICE-ID] - To access specified gpus based on multiple device id, use –gpus device=[YOUR-GPU-DEVICE-ID1],device=[YOUR-GPU-DEVICE-ID2] - To specify more parameters, use `–gpus device=[YOUR-GPU-DEVICE-ID],runtime=nvidia,capabilities=display

RemoteRuntime arguments

--host

The host address of the runtime, by default it is 0.0.0.0.

Default: “0.0.0.0”

--port-jinad

The port of the remote machine for usage with JinaD.

Default: 8000

Distributed arguments

--quiet-remote-logs

Do not display the streaming of remote logs on local console

Default: False

--upload-files

The files on the host to be uploaded to the remote workspace. This can be useful when your Pod has more file dependencies beyond a single YAML file, e.g. Python files, data files.

Note, - currently only flatten structure is supported, which means if you upload [./foo/a.py, ./foo/b.pp, ./bar/c.yml], then they will be put under the _same_ workspace on the remote, losing all hierarchies. - by default, –uses YAML file is always uploaded. - uploaded files are by default isolated across the runs. To ensure files are submitted to the same workspace across different runs, use –workspace-id to specify the workspace.

Pea arguments

--daemon

The Pea attempts to terminate all of its Runtime child processes/threads on existing. setting it to true basically tell the Pea do not wait on the Runtime when closing

Default: False

--runtime-backend, --runtime

Possible choices: THREAD, PROCESS

The parallel backend of the runtime inside the Pea

Default: 1

--runtime-cls

The runtime class to run inside the Pea

Default: “ZEDRuntime”

--timeout-ready

The timeout in milliseconds of a Pea waits for the runtime to be ready, -1 for waiting forever

Default: 600000

--env

The map of environment variables that are available inside runtime

--expose-public

If set, expose the public IP address to remote when necessary, by default it exposesprivate IP address, which only allows accessing under the same network/subnet. Important to set this to true when the Pea will receive input connections from remote Peas

Default: False

--shards, --parallel

The number of shards in the pod running at the same time, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

--replicas

The number of replicas in the pod, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

Pull arguments

--install-requirements

If set, install requirements.txt in the Hub Executor bundle to local

Default: False

--force

If set, always pull the latest Hub Executor bundle even it exists on local

Default: False

flow

Start a Flow. Flow is how Jina streamlines and distributes Executors.

jina flow [-h] [--name] [--workspace] [--log-config] [--quiet] [--quiet-error]
          [--static-routing-table] [--uses]
          [--env [KEY: VALUE [KEY: VALUE ...]]]
          [--inspect {HANG, REMOVE, COLLECT}]

Essential arguments

--name

The name of this object.

This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - …

When not given, then the default naming strategy will apply.

--workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

Default: “./”

--log-config

The YAML config of the logger used in this object.

Default: “/home/runner/work/jina/jina/jina/resources/logging.default.yml”

--quiet

If set, then no log will be emitted from this object.

Default: False

--quiet-error

If set, then exception stack information will not be added to the log

Default: False

--static-routing-table

Defines if the routing table should be pre computed by the Flow. In this case it is statically defined for each Pod and not send on every data request. Can not be used in combination with external pods

Default: False

Flow Feature arguments

--uses

The YAML file represents a flow

--env

The map of environment variables that are available inside runtime

--inspect

Possible choices: HANG, REMOVE, COLLECT

The strategy on those inspect pods in the flow.

If REMOVE is given then all inspect pods are removed when building the flow.

Default: 2

ping

Ping a Pod and check its network connectivity.

jina ping [-h] [--timeout] [--retries] [--print-response] host port

Positional Arguments

host

The host address of the target Pea, e.g. 0.0.0.0

port

The control port of the target pod/pea

Named Arguments

--timeout

Timeout in millisecond of one check -1 for waiting forever

Default: 3000

--retries

The max number of tried health checks before exit with exit code 1

Default: 3

--print-response

If set, print the response when received

Default: False

gateway

Start a Gateway that receives client Requests via gRPC/REST interface

jina gateway [-h] [--name] [--workspace] [--log-config] [--quiet]
             [--quiet-error] [--static-routing-table] [--zmq-identity]
             [--port-ctrl] [--ctrl-with-ipc] [--timeout-ctrl] [--ssh-server]
             [--ssh-keyfile] [--ssh-password] [--uses]
             [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
             [--uses-metas [KEY: VALUE [KEY: VALUE ...]]]
             [--uses-requests [KEY: VALUE [KEY: VALUE ...]]]
             [--py-modules [PATH [PATH ...]]] [--port-in] [--port-out]
             [--hosts-in-connect [[...]]] [--host-in] [--host-out]
             [--socket-in {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
             [--socket-out {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
             [--memory-hwm]
             [--on-error-strategy {IGNORE, SKIP_HANDLE, THROW_EARLY}]
             [--native] [--runs-in-docker] [--prefetch] [--title]
             [--description] [--cors] [--default-swagger-ui]
             [--no-debug-endpoints] [--no-crud-endpoints] [--expose-endpoints]
             [--uvicorn-kwargs [KEY: VALUE [KEY: VALUE ...]]]
             [--compress {NONE, LZ4, ZLIB, GZIP ... 2 more choices}]
             [--compress-min-bytes] [--compress-min-ratio]
             [--protocol {GRPC, HTTP, WEBSOCKET}] [--host] [--proxy]
             [--port-expose] [--daemon] [--runtime-backend {THREAD, PROCESS}]
             [--runtime-cls] [--timeout-ready]
             [--env [KEY: VALUE [KEY: VALUE ...]]] [--expose-public]
             [--shards] [--replicas]

Named Arguments

--protocol

Possible choices: GRPC, HTTP, WEBSOCKET

Communication protocol between server and client.

Default: 0

Essential arguments

--name

The name of this object.

This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - …

When not given, then the default naming strategy will apply.

Default: “gateway”

--workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

--log-config

The YAML config of the logger used in this object.

Default: “/home/runner/work/jina/jina/jina/resources/logging.default.yml”

--quiet

If set, then no log will be emitted from this object.

Default: False

--quiet-error

If set, then exception stack information will not be added to the log

Default: False

--static-routing-table

Defines if the routing table should be pre computed by the Flow. In this case it is statically defined for each Pod and not send on every data request. Can not be used in combination with external pods

Default: False

ZMQRuntime arguments

--zmq-identity

The identity of a ZMQRuntime. It is used for unique socket identification towards other ZMQRuntimes.

--port-ctrl

The port for controlling the runtime, default a random port between [49152, 65535]

Default: 57727

--ctrl-with-ipc

If set, use ipc protocol for control socket

Default: True

--timeout-ctrl

The timeout in milliseconds of the control request, -1 for waiting forever

Default: 5000

--ssh-server

The SSH server through which the tunnel will be created, can actually be a fully specified [email protected]:port ssh url.

--ssh-keyfile

This specifies a key to be used in ssh login, default None. regular default ssh keys will be used without specifying this argument.

--ssh-password

The ssh password to the ssh server.

ZEDRuntime arguments

--uses

The config of the executor, it could be one of the followings: * an Executor YAML file (.yml, .yaml, .jaml) * a Jina Hub Executor (must start with jinahub:// or jinahub+docker://) * a docker image (must start with docker://) * the string literal of a YAML config (must start with ! or `jtype: `) * the string literal of a JSON config

When use it under Python, one can use the following values additionally: - a Python dict that represents the config - a text file stream has .read() interface

Default: “BaseExecutor”

--uses-with

Dictionary of keyword arguments that will override the with configuration in uses

--uses-metas

Dictionary of keyword arguments that will override the metas configuration in uses

--uses-requests

Dictionary of keyword arguments that will override the requests configuration in uses

--py-modules

The customized python modules need to be imported before loading the executor

Note that the recommended way is to only import a single module - a simple python file, if your executor can be defined in a single file, or an __init__.py file if you have multiple files, which should be structured as a python package. For more details, please see the Executor cookbook

--port-in

The port for input data, default a random port between [49152, 65535]

Default: 33129

--port-out

The port for output data, default a random port between [49152, 65535]

Default: 42169

--hosts-in-connect

The host address for input, by default it is 0.0.0.0

--host-in

The host address for input, by default it is 0.0.0.0

Default: “0.0.0.0”

--host-out

The host address for output, by default it is 0.0.0.0

Default: “0.0.0.0”

--socket-in

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for input port

Default: 1

--socket-out

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for output port

Default: 3

--memory-hwm

The memory high watermark of this pod in Gigabytes, pod will restart when this is reached. -1 means no restriction

Default: -1

--on-error-strategy

Possible choices: IGNORE, SKIP_HANDLE, THROW_EARLY

The skip strategy on exceptions.

  • IGNORE: Ignore it, keep running all Executors in the sequel flow

  • SKIP_HANDLE: Skip all Executors in the sequel, only pre_hook and post_hook are called

  • THROW_EARLY: Immediately throw the exception, the sequel flow will not be running at all

Note, IGNORE, SKIP_EXECUTOR and SKIP_HANDLE do not guarantee the success execution in the sequel flow. If something is wrong in the upstream, it is hard to carry this exception and moving forward without any side-effect.

Default: 0

--native

If set, only native Executors is allowed, and the Executor is always run inside ZEDRuntime.

Default: False

--runs-in-docker

Informs a Pea that runs in a container. Important to properly set networking information

Default: False

Prefetch arguments

--prefetch

Number of requests fetched from the client before feeding into the first Executor.

Used to control the speed of data input into a Flow. 0 disables prefetch (disabled by default)

Default: 0

HTTP Gateway arguments

--title

The title of this HTTP server. It will be used in automatics docs such as Swagger UI.

--description

The description of this HTTP server. It will be used in automatics docs such as Swagger UI.

--cors

If set, a CORS middleware is added to FastAPI frontend to allow cross-origin access.

Default: False

--default-swagger-ui

If set, the default swagger ui is used for /docs endpoint.

Default: False

--no-debug-endpoints

If set, /status /post endpoints are removed from HTTP interface.

Default: False

--no-crud-endpoints

If set, /index, /search, /update, /delete endpoints are removed from HTTP interface.

Any executor that has @requests(on=…) bind with those values will receive data requests.

Default: False

--expose-endpoints

A JSON string that represents a map from executor endpoints (@requests(on=…)) to HTTP endpoints.

--uvicorn-kwargs

Dictionary of kwargs arguments that will be passed to Uvicorn server when starting the server

More details can be found in Uvicorn docs: https://www.uvicorn.org/settings/

Compression arguments

--compress

Possible choices: NONE, LZ4, ZLIB, GZIP, BZ2, LZMA

The compress algorithm used over the entire Flow.

Note that this is not necessarily effective, it depends on the settings of –compress-min-bytes and compress-min-ratio

Default: 0

--compress-min-bytes

The original message size must be larger than this number to trigger the compress algorithm, -1 means disable compression.

Default: 1024

--compress-min-ratio

The compression ratio (uncompressed_size/compressed_size) must be higher than this number to trigger the compress algorithm.

Default: 1.1

Gateway arguments

--host

The host address of the runtime, by default it is 0.0.0.0.

Default: “0.0.0.0”

--proxy

If set, respect the http_proxy and https_proxy environment variables. otherwise, it will unset these proxy variables before start. gRPC seems to prefer no proxy

Default: False

--port-expose

The port that the gateway exposes for clients for GRPC connections.

Default: 36113

Pea arguments

--daemon

The Pea attempts to terminate all of its Runtime child processes/threads on existing. setting it to true basically tell the Pea do not wait on the Runtime when closing

Default: False

--runtime-backend, --runtime

Possible choices: THREAD, PROCESS

The parallel backend of the runtime inside the Pea

Default: 1

--runtime-cls

The runtime class to run inside the Pea

Default: “GRPCRuntime”

--timeout-ready

The timeout in milliseconds of a Pea waits for the runtime to be ready, -1 for waiting forever

Default: 600000

--env

The map of environment variables that are available inside runtime

--expose-public

If set, expose the public IP address to remote when necessary, by default it exposesprivate IP address, which only allows accessing under the same network/subnet. Important to set this to true when the Pea will receive input connections from remote Peas

Default: False

--shards, --parallel

The number of shards in the pod running at the same time, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

--replicas

The number of replicas in the pod, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

hub

Push/Pull an Executor to/from Jina Hub

jina hub [-h] {new, push, pull} ...

subcommands

use %(prog)-8s [sub-command] –help to get detailed information about each sub-command

hub

Possible choices: new, push, pull

Sub-commands:

new

Create a new executor using the template

jina hub new [-h] [--name] [--path] [--advance-configuration] [--description]
             [--keywords] [--url] [--add-dockerfile]
Create Executor arguments
--name

the name of the Executor

--path

the path to store the Executor

--advance-configuration

If set, always set up advance configuration like description, keywords and url

Default: False

--description

the short description of the Executor

--keywords

some keywords to help people search your Executor (separated by space)

--url

the URL of your GitHub repo

--add-dockerfile

If set, add a Dockerfile to the created Executor bundle

Default: False

push

Push an executor package to Jina hub

jina hub push [-h] [--no-usage] [-f DOCKERFILE] [-t] [--force] [--secret]
              [--public | --private]
              path
Named Arguments
--no-usage

If set, Hub executor usage will not be printed.

Default: False

Push arguments
path

The Executor folder to be pushed to Jina Hub

-f, --dockerfile

The file path to the Dockerfile (default is ${cwd}/Dockerfile)

-t, --tag

A list of tags. One can use it to distinguish architecture (e.g. cpu, gpu) or versions (e.g. v1, v2).

One can later fetch a tagged Executor via jinahub[+docker]://MyExecutor/gpu

--force

If set, push will overwrite the Executor on the Hub that shares the same NAME or UUID8 identifier

--secret

The secret for overwrite a Hub executor

Visibility arguments
--public

If set, the pushed executor is visible to public

--private

If set, the pushed executor is invisible to public

pull

Download an executor image/package from Jina hub

jina hub pull [-h] [--no-usage] [--install-requirements] [--force] uri
Positional Arguments
uri

The URI of the executor to pull (e.g., jinahub[+docker]://NAME)

Named Arguments
--no-usage

If set, Hub executor usage will not be printed.

Default: False

Pull arguments
--install-requirements

If set, install requirements.txt in the Hub Executor bundle to local

Default: False

--force

If set, always pull the latest Hub Executor bundle even it exists on local

Default: False

help

Show help text of a CLI argument

jina help [-h] query

Positional Arguments

query

Lookup the usage & mention of the argument name in Jina API. The name can be fuzzy

pea

Start a Pea. You should rarely use this directly unless you are doing low-level orchestration

jina pea [-h] [--name] [--workspace] [--log-config] [--quiet] [--quiet-error]
         [--static-routing-table] [--zmq-identity] [--port-ctrl]
         [--ctrl-with-ipc] [--timeout-ctrl] [--ssh-server] [--ssh-keyfile]
         [--ssh-password] [--uses] [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
         [--uses-metas [KEY: VALUE [KEY: VALUE ...]]]
         [--uses-requests [KEY: VALUE [KEY: VALUE ...]]]
         [--py-modules [PATH [PATH ...]]] [--port-in] [--port-out]
         [--hosts-in-connect [[...]]] [--host-in] [--host-out]
         [--socket-in {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
         [--socket-out {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
         [--memory-hwm]
         [--on-error-strategy {IGNORE, SKIP_HANDLE, THROW_EARLY}] [--native]
         [--runs-in-docker] [--entrypoint]
         [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]] [--pull-latest]
         [--volumes [DIR [DIR ...]]] [--gpus] [--host] [--port-jinad]
         [--quiet-remote-logs] [--upload-files [FILE [FILE ...]]] [--daemon]
         [--runtime-backend {THREAD, PROCESS}] [--runtime-cls]
         [--timeout-ready] [--env [KEY: VALUE [KEY: VALUE ...]]]
         [--expose-public] [--shards] [--replicas] [--install-requirements]
         [--force]

Essential arguments

--name

The name of this object.

This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - …

When not given, then the default naming strategy will apply.

--workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

--log-config

The YAML config of the logger used in this object.

Default: “/home/runner/work/jina/jina/jina/resources/logging.default.yml”

--quiet

If set, then no log will be emitted from this object.

Default: False

--quiet-error

If set, then exception stack information will not be added to the log

Default: False

--static-routing-table

Defines if the routing table should be pre computed by the Flow. In this case it is statically defined for each Pod and not send on every data request. Can not be used in combination with external pods

Default: False

ZMQRuntime arguments

--zmq-identity

The identity of a ZMQRuntime. It is used for unique socket identification towards other ZMQRuntimes.

--port-ctrl

The port for controlling the runtime, default a random port between [49152, 65535]

Default: 54711

--ctrl-with-ipc

If set, use ipc protocol for control socket

Default: False

--timeout-ctrl

The timeout in milliseconds of the control request, -1 for waiting forever

Default: 5000

--ssh-server

The SSH server through which the tunnel will be created, can actually be a fully specified [email protected]:port ssh url.

--ssh-keyfile

This specifies a key to be used in ssh login, default None. regular default ssh keys will be used without specifying this argument.

--ssh-password

The ssh password to the ssh server.

ZEDRuntime arguments

--uses

The config of the executor, it could be one of the followings: * an Executor YAML file (.yml, .yaml, .jaml) * a Jina Hub Executor (must start with jinahub:// or jinahub+docker://) * a docker image (must start with docker://) * the string literal of a YAML config (must start with ! or `jtype: `) * the string literal of a JSON config

When use it under Python, one can use the following values additionally: - a Python dict that represents the config - a text file stream has .read() interface

Default: “BaseExecutor”

--uses-with

Dictionary of keyword arguments that will override the with configuration in uses

--uses-metas

Dictionary of keyword arguments that will override the metas configuration in uses

--uses-requests

Dictionary of keyword arguments that will override the requests configuration in uses

--py-modules

The customized python modules need to be imported before loading the executor

Note that the recommended way is to only import a single module - a simple python file, if your executor can be defined in a single file, or an __init__.py file if you have multiple files, which should be structured as a python package. For more details, please see the Executor cookbook

--port-in

The port for input data, default a random port between [49152, 65535]

Default: 39055

--port-out

The port for output data, default a random port between [49152, 65535]

Default: 43705

--hosts-in-connect

The host address for input, by default it is 0.0.0.0

--host-in

The host address for input, by default it is 0.0.0.0

Default: “0.0.0.0”

--host-out

The host address for output, by default it is 0.0.0.0

Default: “0.0.0.0”

--socket-in

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for input port

Default: 0

--socket-out

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for output port

Default: 2

--memory-hwm

The memory high watermark of this pod in Gigabytes, pod will restart when this is reached. -1 means no restriction

Default: -1

--on-error-strategy

Possible choices: IGNORE, SKIP_HANDLE, THROW_EARLY

The skip strategy on exceptions.

  • IGNORE: Ignore it, keep running all Executors in the sequel flow

  • SKIP_HANDLE: Skip all Executors in the sequel, only pre_hook and post_hook are called

  • THROW_EARLY: Immediately throw the exception, the sequel flow will not be running at all

Note, IGNORE, SKIP_EXECUTOR and SKIP_HANDLE do not guarantee the success execution in the sequel flow. If something is wrong in the upstream, it is hard to carry this exception and moving forward without any side-effect.

Default: 0

--native

If set, only native Executors is allowed, and the Executor is always run inside ZEDRuntime.

Default: False

--runs-in-docker

Informs a Pea that runs in a container. Important to properly set networking information

Default: False

ContainerRuntime arguments

--entrypoint

The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective.

--docker-kwargs

Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘ container.

More details can be found in the Docker SDK docs: https://docker-py.readthedocs.io/en/stable/

--pull-latest

Pull the latest image before running

Default: False

--volumes

The path on the host to be mounted inside the container.

Note, - If separated by :, then the first part will be considered as the local host path and the second part is the path in the container system. - If no split provided, then the basename of that directory will be mounted into container’s root path, e.g. –volumes=”/user/test/my-workspace” will be mounted into /my-workspace inside the container. - All volumes are mounted with read-write mode.

--gpus

This argument allows dockerized Jina executor discover local gpu devices.

Note, - To access all gpus, use –gpus all. - To access multiple gpus, e.g. make use of 2 gpus, use –gpus 2. - To access specified gpus based on device id, use –gpus device=[YOUR-GPU-DEVICE-ID] - To access specified gpus based on multiple device id, use –gpus device=[YOUR-GPU-DEVICE-ID1],device=[YOUR-GPU-DEVICE-ID2] - To specify more parameters, use `–gpus device=[YOUR-GPU-DEVICE-ID],runtime=nvidia,capabilities=display

RemoteRuntime arguments

--host

The host address of the runtime, by default it is 0.0.0.0.

Default: “0.0.0.0”

--port-jinad

The port of the remote machine for usage with JinaD.

Default: 8000

Distributed arguments

--quiet-remote-logs

Do not display the streaming of remote logs on local console

Default: False

--upload-files

The files on the host to be uploaded to the remote workspace. This can be useful when your Pod has more file dependencies beyond a single YAML file, e.g. Python files, data files.

Note, - currently only flatten structure is supported, which means if you upload [./foo/a.py, ./foo/b.pp, ./bar/c.yml], then they will be put under the _same_ workspace on the remote, losing all hierarchies. - by default, –uses YAML file is always uploaded. - uploaded files are by default isolated across the runs. To ensure files are submitted to the same workspace across different runs, use –workspace-id to specify the workspace.

Pea arguments

--daemon

The Pea attempts to terminate all of its Runtime child processes/threads on existing. setting it to true basically tell the Pea do not wait on the Runtime when closing

Default: False

--runtime-backend, --runtime

Possible choices: THREAD, PROCESS

The parallel backend of the runtime inside the Pea

Default: 1

--runtime-cls

The runtime class to run inside the Pea

Default: “ZEDRuntime”

--timeout-ready

The timeout in milliseconds of a Pea waits for the runtime to be ready, -1 for waiting forever

Default: 600000

--env

The map of environment variables that are available inside runtime

--expose-public

If set, expose the public IP address to remote when necessary, by default it exposesprivate IP address, which only allows accessing under the same network/subnet. Important to set this to true when the Pea will receive input connections from remote Peas

Default: False

--shards, --parallel

The number of shards in the pod running at the same time, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

--replicas

The number of replicas in the pod, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

Pull arguments

--install-requirements

If set, install requirements.txt in the Hub Executor bundle to local

Default: False

--force

If set, always pull the latest Hub Executor bundle even it exists on local

Default: False

pod

Start a Pod. You should rarely use this directly unless you are doing low-level orchestration

jina pod [-h] [--name] [--workspace] [--log-config] [--quiet] [--quiet-error]
         [--static-routing-table] [--zmq-identity] [--port-ctrl]
         [--ctrl-with-ipc] [--timeout-ctrl] [--ssh-server] [--ssh-keyfile]
         [--ssh-password] [--uses] [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
         [--uses-metas [KEY: VALUE [KEY: VALUE ...]]]
         [--uses-requests [KEY: VALUE [KEY: VALUE ...]]]
         [--py-modules [PATH [PATH ...]]] [--port-in] [--port-out]
         [--hosts-in-connect [[...]]] [--host-in] [--host-out]
         [--socket-in {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
         [--socket-out {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 9 more choices}]
         [--memory-hwm]
         [--on-error-strategy {IGNORE, SKIP_HANDLE, THROW_EARLY}] [--native]
         [--runs-in-docker] [--entrypoint]
         [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]] [--pull-latest]
         [--volumes [DIR [DIR ...]]] [--gpus] [--host] [--port-jinad]
         [--quiet-remote-logs] [--upload-files [FILE [FILE ...]]] [--daemon]
         [--runtime-backend {THREAD, PROCESS}] [--runtime-cls]
         [--timeout-ready] [--env [KEY: VALUE [KEY: VALUE ...]]]
         [--expose-public] [--shards] [--replicas] [--install-requirements]
         [--force] [--uses-before] [--uses-after]
         [--polling {ANY, ALL, ALL_ASYNC}]
         [--scheduling {LOAD_BALANCE, ROUND_ROBIN}] [--external]
         [--peas-hosts  [...]] [--no-dynamic-routing]
         [--connect-to-predecessor]

Named Arguments

--no-dynamic-routing

The Pod will setup the socket types of the HeadPea and TailPea depending on this argument.

Default: True

--connect-to-predecessor

The head Pea of this Pod will connect to the TailPea of the predecessor Pod.

Default: False

Essential arguments

--name

The name of this object.

This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - …

When not given, then the default naming strategy will apply.

--workspace

The working directory for any IO operations in this object. If not set, then derive from its parent workspace.

--log-config

The YAML config of the logger used in this object.

Default: “/home/runner/work/jina/jina/jina/resources/logging.default.yml”

--quiet

If set, then no log will be emitted from this object.

Default: False

--quiet-error

If set, then exception stack information will not be added to the log

Default: False

--static-routing-table

Defines if the routing table should be pre computed by the Flow. In this case it is statically defined for each Pod and not send on every data request. Can not be used in combination with external pods

Default: False

ZMQRuntime arguments

--zmq-identity

The identity of a ZMQRuntime. It is used for unique socket identification towards other ZMQRuntimes.

--port-ctrl

The port for controlling the runtime, default a random port between [49152, 65535]

Default: 46449

--ctrl-with-ipc

If set, use ipc protocol for control socket

Default: False

--timeout-ctrl

The timeout in milliseconds of the control request, -1 for waiting forever

Default: 5000

--ssh-server

The SSH server through which the tunnel will be created, can actually be a fully specified [email protected]:port ssh url.

--ssh-keyfile

This specifies a key to be used in ssh login, default None. regular default ssh keys will be used without specifying this argument.

--ssh-password

The ssh password to the ssh server.

ZEDRuntime arguments

--uses

The config of the executor, it could be one of the followings: * an Executor YAML file (.yml, .yaml, .jaml) * a Jina Hub Executor (must start with jinahub:// or jinahub+docker://) * a docker image (must start with docker://) * the string literal of a YAML config (must start with ! or `jtype: `) * the string literal of a JSON config

When use it under Python, one can use the following values additionally: - a Python dict that represents the config - a text file stream has .read() interface

Default: “BaseExecutor”

--uses-with

Dictionary of keyword arguments that will override the with configuration in uses

--uses-metas

Dictionary of keyword arguments that will override the metas configuration in uses

--uses-requests

Dictionary of keyword arguments that will override the requests configuration in uses

--py-modules

The customized python modules need to be imported before loading the executor

Note that the recommended way is to only import a single module - a simple python file, if your executor can be defined in a single file, or an __init__.py file if you have multiple files, which should be structured as a python package. For more details, please see the Executor cookbook

--port-in

The port for input data, default a random port between [49152, 65535]

Default: 32927

--port-out

The port for output data, default a random port between [49152, 65535]

Default: 52441

--hosts-in-connect

The host address for input, by default it is 0.0.0.0

--host-in

The host address for input, by default it is 0.0.0.0

Default: “0.0.0.0”

--host-out

The host address for output, by default it is 0.0.0.0

Default: “0.0.0.0”

--socket-in

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for input port

Default: 0

--socket-out

Possible choices: PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT, SUB_BIND, SUB_CONNECT, PUB_BIND, PUB_CONNECT, PAIR_BIND, PAIR_CONNECT, ROUTER_BIND, DEALER_CONNECT, ROUTER_CONNECT

The socket type for output port

Default: 2

--memory-hwm

The memory high watermark of this pod in Gigabytes, pod will restart when this is reached. -1 means no restriction

Default: -1

--on-error-strategy

Possible choices: IGNORE, SKIP_HANDLE, THROW_EARLY

The skip strategy on exceptions.

  • IGNORE: Ignore it, keep running all Executors in the sequel flow

  • SKIP_HANDLE: Skip all Executors in the sequel, only pre_hook and post_hook are called

  • THROW_EARLY: Immediately throw the exception, the sequel flow will not be running at all

Note, IGNORE, SKIP_EXECUTOR and SKIP_HANDLE do not guarantee the success execution in the sequel flow. If something is wrong in the upstream, it is hard to carry this exception and moving forward without any side-effect.

Default: 0

--native

If set, only native Executors is allowed, and the Executor is always run inside ZEDRuntime.

Default: False

--runs-in-docker

Informs a Pea that runs in a container. Important to properly set networking information

Default: False

ContainerRuntime arguments

--entrypoint

The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective.

--docker-kwargs

Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘ container.

More details can be found in the Docker SDK docs: https://docker-py.readthedocs.io/en/stable/

--pull-latest

Pull the latest image before running

Default: False

--volumes

The path on the host to be mounted inside the container.

Note, - If separated by :, then the first part will be considered as the local host path and the second part is the path in the container system. - If no split provided, then the basename of that directory will be mounted into container’s root path, e.g. –volumes=”/user/test/my-workspace” will be mounted into /my-workspace inside the container. - All volumes are mounted with read-write mode.

--gpus

This argument allows dockerized Jina executor discover local gpu devices.

Note, - To access all gpus, use –gpus all. - To access multiple gpus, e.g. make use of 2 gpus, use –gpus 2. - To access specified gpus based on device id, use –gpus device=[YOUR-GPU-DEVICE-ID] - To access specified gpus based on multiple device id, use –gpus device=[YOUR-GPU-DEVICE-ID1],device=[YOUR-GPU-DEVICE-ID2] - To specify more parameters, use `–gpus device=[YOUR-GPU-DEVICE-ID],runtime=nvidia,capabilities=display

RemoteRuntime arguments

--host

The host address of the runtime, by default it is 0.0.0.0.

Default: “0.0.0.0”

--port-jinad

The port of the remote machine for usage with JinaD.

Default: 8000

Distributed arguments

--quiet-remote-logs

Do not display the streaming of remote logs on local console

Default: False

--upload-files

The files on the host to be uploaded to the remote workspace. This can be useful when your Pod has more file dependencies beyond a single YAML file, e.g. Python files, data files.

Note, - currently only flatten structure is supported, which means if you upload [./foo/a.py, ./foo/b.pp, ./bar/c.yml], then they will be put under the _same_ workspace on the remote, losing all hierarchies. - by default, –uses YAML file is always uploaded. - uploaded files are by default isolated across the runs. To ensure files are submitted to the same workspace across different runs, use –workspace-id to specify the workspace.

Pea arguments

--daemon

The Pea attempts to terminate all of its Runtime child processes/threads on existing. setting it to true basically tell the Pea do not wait on the Runtime when closing

Default: False

--runtime-backend, --runtime

Possible choices: THREAD, PROCESS

The parallel backend of the runtime inside the Pea

Default: 1

--runtime-cls

The runtime class to run inside the Pea

Default: “ZEDRuntime”

--timeout-ready

The timeout in milliseconds of a Pea waits for the runtime to be ready, -1 for waiting forever

Default: 600000

--env

The map of environment variables that are available inside runtime

--expose-public

If set, expose the public IP address to remote when necessary, by default it exposesprivate IP address, which only allows accessing under the same network/subnet. Important to set this to true when the Pea will receive input connections from remote Peas

Default: False

--shards, --parallel

The number of shards in the pod running at the same time, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

--replicas

The number of replicas in the pod, port_in and port_out will be set to random, and routers will be added automatically when necessary

Default: 1

Pull arguments

--install-requirements

If set, install requirements.txt in the Hub Executor bundle to local

Default: False

--force

If set, always pull the latest Hub Executor bundle even it exists on local

Default: False

Pod arguments

--uses-before

The executor attached after the Peas described by –uses, typically before sending to all shards, accepted type follows –uses

--uses-after

The executor attached after the Peas described by –uses, typically used for receiving from all shards, accepted type follows –uses

--polling

Possible choices: ANY, ALL, ALL_ASYNC

The polling strategy of the Pod (when shards>1) - ANY: only one (whoever is idle) Pea polls the message - ALL: all Peas poll the message (like a broadcast)

Default: 1

--scheduling

Possible choices: LOAD_BALANCE, ROUND_ROBIN

The strategy of scheduling workload among Peas

Default: 0

--external

The Pod will be considered an external Pod that has been started independently from the Flow.This Pod will not be context managed by the Flow.

Default: False

--peas-hosts
The hosts of the peas when shards greater than 1.

Peas will be evenly distributed among the hosts. By default, peas are running on host provided by the argument host

client

Start a Python client that connects to a remote Jina gateway

jina client [-h] [--host] [--proxy] [--port] [--https] [--asyncio]
            [--protocol {GRPC, HTTP, WEBSOCKET}]

Named Arguments

--asyncio

If set, then the input and output of this Client work in an asynchronous manner.

Default: False

--protocol

Possible choices: GRPC, HTTP, WEBSOCKET

Communication protocol between server and client.

Default: 0

ClientGateway arguments

--host

The host address of the runtime, by default it is 0.0.0.0.

Default: “0.0.0.0”

--proxy

If set, respect the http_proxy and https_proxy environment variables. otherwise, it will unset these proxy variables before start. gRPC seems to prefer no proxy

Default: False

--port

The port of the Gateway, which the client should connect to.

Default: 54481

--https

If set, connect to gateway using https

Default: False

export-api

Export Jina API to JSON/YAML file for 3rd party applications

jina export-api [-h] [--yaml-path [PATH [PATH ...]]]
                [--json-path [PATH [PATH ...]]]
                [--schema-path [PATH [PATH ...]]]

Named Arguments

--yaml-path

The YAML file path for storing the exported API

--json-path

The JSON file path for storing the exported API

--schema-path

The JSONSchema file path for storing the exported API