Jina Command-Line Interface

usage: jina [-h] [-v] [-vf]
            {hello, executor, pod, flow ... 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, pod, flow, ping, gateway, hub, help, pea, 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] [--request-size] [--num-query]
                   [--top-k]
General arguments
--workdir

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

Default: “7e9695d9-49f5-421b-a9e5-6935108565c8”

--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] [--parallel]
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

--parallel

The number of parallel 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: “17231160-4b0b-4e97-bc11-fa15fb23caa6”

--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: “37481a56-a812-4502-8c31-e17cf53a8cf8”

--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 (pod)

Start an Executor. Executor is how Jina processes Document.

jina executor [-h] [--name] [--workspace] [--log-config] [--quiet]
              [--quiet-error] [--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 ...]]]
              [--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}]
              [--num-part] [--dynamic-routing] [--dynamic-routing-out]
              [--dynamic-routing-in] [--entrypoint]
              [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]] [--pull-latest]
              [--volumes [DIR [DIR ...]]] [--gpus] [--host] [--port-expose]
              [--proxy] [--quiet-remote-logs]
              [--upload-files [FILE [FILE ...]]] [--disable-remote] [--daemon]
              [--runtime-backend {THREAD, PROCESS}] [--runtime-cls]
              [--timeout-ready] [--env [KEY: VALUE [KEY: VALUE ...]]]
              [--expose-public] [--pea-id]
              [--pea-role {SINGLETON, HEAD, TAIL, PARALLEL}]
              [--noblock-on-start] [--runs-in-docker] [--uses-before]
              [--uses-after] [--parallel] [--replicas]
              [--polling {ANY, ALL, ALL_ASYNC}]
              [--scheduling {LOAD_BALANCE, ROUND_ROBIN}] [--external]
              [--peas-hosts  [...]]
              [--pod-role {POD, JOIN, INSPECT, GATEWAY ... 2 more choices}]

Named Arguments

--dynamic-routing

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

Default: True

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

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

--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, --override-with

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

--uses-metas, --override-metas

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

--py-modules

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

Note, when importing multiple files and there is a dependency between them, then one has to write the dependencies in reverse order. That is, if __init__.py depends on A.py, which again depends on B.py, then you need to write:

–py-modules __init__.py –py-modules B.py –py-modules A.py

--port-in

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

Default: 34527

--port-out

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

Default: 45407

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

--num-part

the number of messages expected from upstream, 0 and 1 means single part

Default: 0

--dynamic-routing-out

Tells if ZEDRuntime should respect routing graph for outgoing traffic.

Default: False

--dynamic-routing-in

Tells if ZEDRuntime should handle incoming traffic as dynamic routing.

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

Expose arguments

--host

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

Default: “0.0.0.0”

--port-expose

The port of the host exposed to the public

Default: 56583

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

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.

--disable-remote

If set, remote pea invocation is avoided. This is used by peas created by JinaD

Default: False

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

--pea-id

defines the suffix for the workspace path of the pea`

Default: 0

--pea-role

Possible choices: SINGLETON, HEAD, TAIL, PARALLEL

The role of this Pea in a Pod

Default: 0

--noblock-on-start

If set, starting a Pea/Pod does not block the thread/process. It then relies on wait_start_success at outer function for the postpone check.

Default: False

--runs-in-docker

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

Default: False

Pod arguments

--uses-before

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

--uses-after

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

--parallel, --shards

The number of parallel peas 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

--polling

Possible choices: ANY, ALL, ALL_ASYNC

The polling strategy of the Pod (when parallel>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 parallel greater than 1.

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

--pod-role

Possible choices: POD, JOIN, INSPECT, GATEWAY, INSPECT_AUX_PASS, JOIN_INSPECT

The role of this pod in the flow

flow

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

jina flow [-h] [--name] [--workspace] [--log-config] [--quiet] [--quiet-error]
          [--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

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] [--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 ...]]]
             [--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}]
             [--num-part] [--dynamic-routing] [--dynamic-routing-out]
             [--dynamic-routing-in] [--prefetch] [--prefetch-on-recv]
             [--title] [--description] [--cors] [--default-swagger-ui]
             [--no-debug-endpoints] [--no-crud-endpoints] [--expose-endpoints]
             [--compress {NONE, LZ4, ZLIB, GZIP ... 2 more choices}]
             [--compress-min-bytes] [--compress-min-ratio]
             [--protocol {GRPC, HTTP, WEBSOCKET}] [--host] [--port-expose]
             [--proxy] [--daemon] [--runtime-backend {THREAD, PROCESS}]
             [--runtime-cls] [--timeout-ready]
             [--env [KEY: VALUE [KEY: VALUE ...]]] [--expose-public]
             [--pea-id] [--pea-role {SINGLETON, HEAD, TAIL, PARALLEL}]
             [--noblock-on-start] [--runs-in-docker]

Named Arguments

--dynamic-routing

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

Default: True

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

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

--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, --override-with

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

--uses-metas, --override-metas

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

--py-modules

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

Note, when importing multiple files and there is a dependency between them, then one has to write the dependencies in reverse order. That is, if __init__.py depends on A.py, which again depends on B.py, then you need to write:

–py-modules __init__.py –py-modules B.py –py-modules A.py

--port-in

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

Default: 50143

--port-out

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

Default: 48373

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

--num-part

the number of messages expected from upstream, 0 and 1 means single part

Default: 0

--dynamic-routing-out

Tells if ZEDRuntime should respect routing graph for outgoing traffic.

Default: False

--dynamic-routing-in

Tells if ZEDRuntime should handle incoming traffic as dynamic routing.

Default: False

Prefetch arguments

--prefetch

The number of pre-fetched requests from the client

Default: 50

--prefetch-on-recv

The number of additional requests to fetch on every receive

Default: 1

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.

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

Expose arguments

--host

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

Default: “0.0.0.0”

--port-expose

The port of the host exposed to the public

Default: 60651

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

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

--pea-id

defines the suffix for the workspace path of the pea`

Default: 0

--pea-role

Possible choices: SINGLETON, HEAD, TAIL, PARALLEL

The role of this Pea in a Pod

Default: 0

--noblock-on-start

If set, starting a Pea/Pod does not block the thread/process. It then relies on wait_start_success at outer function for the postpone check.

Default: False

--runs-in-docker

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

Default: False

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]
push

Push an executor package to Jina hub

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

If set, Hub executor usage will not be printed.

Default: False

Push arguments
path

The content source to be shipped into a Jina Hub executor. It can one of the followings: - a directory containing Dockerfile, manifest.yml, README.md, zero or more yaml config, zero or more Python file.

--force

To overwrite the executor identified as UUID8

--secret

The secret key of the identified Jina 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] uri
Named Arguments
--no-usage

If set, Hub executor usage will not be printed.

Default: False

Pull arguments
uri

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

--install-requirements

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

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]
         [--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 ...]]]
         [--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}] [--num-part]
         [--dynamic-routing] [--dynamic-routing-out] [--dynamic-routing-in]
         [--entrypoint] [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]]
         [--pull-latest] [--volumes [DIR [DIR ...]]] [--gpus] [--host]
         [--port-expose] [--proxy] [--quiet-remote-logs]
         [--upload-files [FILE [FILE ...]]] [--disable-remote] [--daemon]
         [--runtime-backend {THREAD, PROCESS}] [--runtime-cls]
         [--timeout-ready] [--env [KEY: VALUE [KEY: VALUE ...]]]
         [--expose-public] [--pea-id]
         [--pea-role {SINGLETON, HEAD, TAIL, PARALLEL}] [--noblock-on-start]
         [--runs-in-docker]

Named Arguments

--dynamic-routing

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

Default: True

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

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

--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, --override-with

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

--uses-metas, --override-metas

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

--py-modules

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

Note, when importing multiple files and there is a dependency between them, then one has to write the dependencies in reverse order. That is, if __init__.py depends on A.py, which again depends on B.py, then you need to write:

–py-modules __init__.py –py-modules B.py –py-modules A.py

--port-in

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

Default: 49187

--port-out

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

Default: 52515

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

--num-part

the number of messages expected from upstream, 0 and 1 means single part

Default: 0

--dynamic-routing-out

Tells if ZEDRuntime should respect routing graph for outgoing traffic.

Default: False

--dynamic-routing-in

Tells if ZEDRuntime should handle incoming traffic as dynamic routing.

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

Expose arguments

--host

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

Default: “0.0.0.0”

--port-expose

The port of the host exposed to the public

Default: 48121

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

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.

--disable-remote

If set, remote pea invocation is avoided. This is used by peas created by JinaD

Default: False

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

--pea-id

defines the suffix for the workspace path of the pea`

Default: 0

--pea-role

Possible choices: SINGLETON, HEAD, TAIL, PARALLEL

The role of this Pea in a Pod

Default: 0

--noblock-on-start

If set, starting a Pea/Pod does not block the thread/process. It then relies on wait_start_success at outer function for the postpone check.

Default: False

--runs-in-docker

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

Default: False

client

Start a Python client that connects to a remote Jina gateway

jina client [-h] [--host] [--port-expose] [--proxy] [--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

Expose arguments

--host

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

Default: “0.0.0.0”

--port-expose

The port of the host exposed to the public

Default: 38307

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

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