Command-Line Interface#

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

Positional Arguments#

cli: Possible choices: executor, flow, ping, export, new, gateway, auth, hub, cloud, help, pod, deployment, client

Named Arguments#

-v, --version: Show Jina version
-vf, --version-full: Show Jina and all dependencies’ versions

Sub-commands:#

executor#

Start an Executor. Executor is how Jina processes Document.

jina executor [-h] [--name] [--workspace] [--log-config] [--quiet]
              [--quiet-error] [--timeout-ctrl] [--polling] [--shards]
              [--replicas] [--native] [--uses]
              [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
              [--uses-metas [KEY: VALUE [KEY: VALUE ...]]]
              [--uses-requests [KEY: VALUE [KEY: VALUE ...]]]
              [--uses-dynamic-batching [KEY: VALUE [KEY: VALUE ...]]]
              [--py-modules [PATH [PATH ...]]] [--output-array-type]
              [--exit-on-exceptions [[...]]] [--no-reduce]
              [--grpc-server-options [KEY: VALUE [KEY: VALUE ...]]]
              [--entrypoint] [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]]
              [--volumes [DIR [DIR ...]]] [--gpus] [--disable-auto-volume]
              [--host  [...]] [--runtime-cls] [--timeout-ready]
              [--env [KEY: VALUE [KEY: VALUE ...]]] [--floating] [--reload]
              [--install-requirements] [--port  [...]] [--monitoring]
              [--port-monitoring  [...]] [--retries] [--tracing]
              [--traces-exporter-host] [--traces-exporter-port] [--metrics]
              [--metrics-exporter-host] [--metrics-exporter-port]
              [--force-update] [--compression {NoCompression, Deflate, Gzip}]
              [--uses-before-address] [--uses-after-address]
              [--connection-list] [--timeout-send]

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: “default”

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

Scalable Deployment arguments#

--timeout-ctrl

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

Default: 60

--polling

The polling strategy of the Deployment and its endpoints (when shards>1). Can be defined for all endpoints of a Deployment or by endpoint. Define per Deployment: - ANY: only one (whoever is idle) Pod polls the message - ALL: all Pods poll the message (like a broadcast) Define per Endpoint: JSON dict, {endpoint: PollingType} {‘/custom’: ‘ALL’, ‘/search’: ‘ANY’, ‘*’: ‘ANY’}

Default: “ANY”

--shards

The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/concepts/flow/create-flow/#complex-flow-topologies

Default: 1

--replicas

The number of replicas in the deployment

Default: 1

--native

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

Default: False

WorkerRuntime arguments#

--uses

The config of the executor, it could be one of the followings: * the string literal of an Executor class name * 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

--uses-dynamic-batching

Dictionary of keyword arguments that will override the dynamic_batching 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

--output-array-type

The type of array tensor and embedding will be serialized to.

Supports the same types as docarray.to_protobuf(.., ndarray_type=…), which can be found here <https://docarray.jina.ai/fundamentals/document/serialization/#from-to-protobuf>. Defaults to retaining whatever type is returned by the Executor.

--exit-on-exceptions

List of exceptions that will cause the Executor to shut down.

Default: []

--no-reduce, --disable-reduce

Disable the built-in reduction mechanism. Set this if the reduction is to be handled by the Executor itself by operating on a docs_matrix or docs_map

Default: False

--grpc-server-options

Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1}

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/

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

--disable-auto-volume

Do not automatically mount a volume for dockerized Executors.

Default: False

RemoteRuntime arguments#

--host, --host-in

The host of the Gateway, which the client should connect to, by default it is 0.0.0.0. In the case of an external Executor (–external or external=True) this can be a list of hosts. Then, every resulting address will be considered as one replica of the Executor.

Default: [‘0.0.0.0’]

Pod arguments#

--runtime-cls

The runtime class to run inside the Pod

Default: “WorkerRuntime”

--timeout-ready

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

Default: 600000

--env

The map of environment variables that are available inside runtime

--floating

If set, the current Pod/Deployment can not be further chained, and the next .add() will chain after the last Pod/Deployment not this current one.

Default: False

--reload

If set, the Executor will restart while serving if YAML configuration source or Executor modules are changed. If YAML configuration is changed, the whole deployment is reloaded and new processes will be restarted. If only Python modules of the Executor have changed, they will be reloaded to the interpreter without restarting process.

Default: False

--install-requirements

If set, try to install requirements.txt from the local Executor if exists in the Executor folder. If using Hub, install requirements.txt in the Hub Executor bundle to local.

Default: False

--port, --port-in

The port for input data to bind to, default is a random port between [49152, 65535]. In the case of an external Executor (–external or external=True) this can be a list of ports. Then, every resulting address will be considered as one replica of the Executor.

Default: [54742]

--monitoring

If set, spawn an http server with a prometheus endpoint to expose metrics

Default: False

--port-monitoring

The port on which the prometheus server is exposed, default is a random port between [49152, 65535]

Default: [56377]

--retries

Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)

Default: -1

--tracing

If set, the sdk implementation of the OpenTelemetry tracer will be available and will be enabled for automatic tracing of requests and customer span creation. Otherwise a no-op implementation will be provided.

Default: False

--traces-exporter-host

If tracing is enabled, this hostname will be used to configure the trace exporter agent.

--traces-exporter-port

If tracing is enabled, this port will be used to configure the trace exporter agent.

--metrics

If set, the sdk implementation of the OpenTelemetry metrics will be available for default monitoring and custom measurements. Otherwise a no-op implementation will be provided.

Default: False

--metrics-exporter-host

If tracing is enabled, this hostname will be used to configure the metrics exporter agent.

--metrics-exporter-port

If tracing is enabled, this port will be used to configure the metrics exporter agent.

Pull arguments#

--force-update, --force

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

Default: False

Head arguments#

--compression

Possible choices: NoCompression, Deflate, Gzip

The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.

--uses-before-address

The address of the uses-before runtime

--uses-after-address

The address of the uses-before runtime

--connection-list

dictionary JSON with a list of connections to configure

--timeout-send

The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default

flow#

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

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

--log-config

The YAML config of the logger used in this object.

Default: “default”

--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 path represents a flow. It can be either a local file path or a URL.

--reload

If set, auto-reloading on file changes is enabled: the Flow will restart while blocked if YAML configuration source is changed. This also applies apply to underlying Executors, if their source code or YAML configuration has changed.

Default: False

--env

The map of environment variables that are available inside runtime

--inspect

Possible choices: HANG, REMOVE, COLLECT

The strategy on those inspect deployments in the flow.

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

Default: COLLECT

ping#

Ping a remote Executor or a Flow.

jina ping [-h] [--timeout] [--attempts] [--min-successful-attempts]
          {flow, executor, gateway} host

Positional Arguments#

target

Possible choices: flow, executor, gateway

The target type to ping. For executor and gateway, checks the readiness of the individual service. For flow it checks the connectivity of the complete microservice architecture.

Default: “executor”

host

The host address with port of a target Executor, Gateway or a Flow, e.g. 0.0.0.0:8000. For Flow or Gateway, host can also indicate the protocol, grpc will be used if not provided, e.g http://0.0.0.0:8000

Named Arguments#

--timeout

Timeout in millisecond of one check -1 for waiting forever

Default: 3000

--attempts

The number of readiness checks to perform

Default: 1

--min-successful-attempts

The minimum number of successful readiness checks, before exiting successfully with exit(0)

Default: 1

export#

Export Jina API and Flow to JSONSchema, Kubernetes YAML, or SVG flowchart.

jina export [-h] {flowchart, kubernetes, docker-compose, schema} ...

subcommands#

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

export: Possible choices: flowchart, kubernetes, docker-compose, schema

Sub-commands:#

flowchart#

Export a Flow YAML file to a flowchart

jina export flowchart [-h] [--vertical-layout] INPUT OUTPUT

Positional Arguments#

INPUT: The input file path of a Flow YAML
OUTPUT: The output path

Named Arguments#

--vertical-layout

If set, then the flowchart is rendered vertically from top to down.

Default: False

kubernetes#

Export a Flow YAML file to a Kubernetes YAML bundle

jina export kubernetes [-h] [--k8s-namespace] INPUT OUTPUT

Positional Arguments#

INPUT: The input file path of a Flow YAML
OUTPUT: The output path

Named Arguments#

--k8s-namespace: The name of the k8s namespace to set for the configurations. If None, the name of the Flow will be used.

docker-compose#

Export a Flow YAML file to a Docker Compose YAML file

jina export docker-compose [-h] [--network_name] INPUT OUTPUT

Positional Arguments#

INPUT: The input file path of a Flow YAML
OUTPUT: The output path

Named Arguments#

--network_name: The name of the network that will be used by the deployment name.

schema#

Export Jina Executor & Flow API to JSONSchema files

jina export schema [-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

new#

Create a new Jina toy project with the predefined template.

jina new [-h] name

Positional Arguments#

name

The name of the project

Default: “hello-jina”

gateway#

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

jina gateway [-h] [--name] [--workspace] [--log-config] [--quiet]
             [--quiet-error] [--timeout-ctrl] [--entrypoint]
             [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]] [--prefetch]
             [--title] [--description] [--cors] [--no-debug-endpoints]
             [--no-crud-endpoints] [--expose-endpoints]
             [--uvicorn-kwargs [KEY: VALUE [KEY: VALUE ...]]] [--ssl-certfile]
             [--ssl-keyfile] [--expose-graphql-endpoint]
             [--protocol {GRPC, HTTP, WEBSOCKET} [{GRPC, HTTP, WEBSOCKET} ...]]
             [--host] [--proxy] [--uses]
             [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
             [--py-modules [PATH [PATH ...]]]
             [--grpc-server-options [KEY: VALUE [KEY: VALUE ...]]]
             [--graph-description] [--graph-conditions]
             [--deployments-addresses] [--deployments-metadata]
             [--deployments-no-reduce]
             [--compression {NoCompression, Deflate, Gzip}] [--timeout-send]
             [--runtime-cls] [--timeout-ready]
             [--env [KEY: VALUE [KEY: VALUE ...]]] [--floating] [--reload]
             [--port  [...]] [--monitoring] [--port-monitoring  [...]]
             [--retries] [--tracing] [--traces-exporter-host]
             [--traces-exporter-port] [--metrics] [--metrics-exporter-host]
             [--metrics-exporter-port]

Named Arguments#

--protocol, --protocols

Possible choices: GRPC, HTTP, WEBSOCKET

Communication protocol of the server exposed by the Gateway. This can be a single value or a list of protocols, depending on your chosen Gateway. Choose the convenient protocols from: [‘GRPC’, ‘HTTP’, ‘WEBSOCKET’].

Default: [<GatewayProtocolType.GRPC: 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: “default”

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

Base Deployment arguments#

--timeout-ctrl

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

Default: 60

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/

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 (1000 requests is the default)

Default: 1000

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

--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=…) bound 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/

--ssl-certfile

the path to the certificate file

--ssl-keyfile

the path to the key file

GraphQL arguments#

--expose-graphql-endpoint

If set, /graphql endpoint is added to HTTP interface.

Default: False

Gateway arguments#

--host, --host-in

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

--uses

The config of the gateway, it could be one of the followings: * the string literal of an Gateway class name * a Gateway YAML file (.yml, .yaml, .jaml) * 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

--uses-with

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

--py-modules

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

Note that the recommended way is to only import a single module - a simple python file, if your gateway 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.

--grpc-server-options

Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1}

--graph-description

Routing graph for the gateway

Default: “{}”

--graph-conditions

Dictionary stating which filtering conditions each Executor in the graph requires to receive Documents.

Default: “{}”

--deployments-addresses

JSON dictionary with the input addresses of each Deployment

Default: “{}”

--deployments-metadata

JSON dictionary with the request metadata for each Deployment

Default: “{}”

--deployments-no-reduce, --deployments-disable-reduce

list JSON disabling the built-in merging mechanism for each Deployment listed

Default: “[]”

--compression

Possible choices: NoCompression, Deflate, Gzip

The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.

--timeout-send

The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default

Pod arguments#

--runtime-cls

The runtime class to run inside the Pod

Default: “GatewayRuntime”

--timeout-ready

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

Default: 600000

--env

The map of environment variables that are available inside runtime

--floating

If set, the current Pod/Deployment can not be further chained, and the next .add() will chain after the last Pod/Deployment not this current one.

Default: False

--reload

If set, the Gateway will restart while serving if YAML configuration source is changed.

Default: False

--port, --port-expose, --port-in, --ports

The port for input data to bind the gateway server to, by default, random ports between range [49152, 65535] will be assigned. The port argument can be either 1 single value in case only 1 protocol is used or multiple values when many protocols are used.

--monitoring

If set, spawn an http server with a prometheus endpoint to expose metrics

Default: False

--port-monitoring

The port on which the prometheus server is exposed, default is a random port between [49152, 65535]

Default: [59098]

--retries

Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)

Default: -1

--tracing

Default: False

--traces-exporter-host

If tracing is enabled, this hostname will be used to configure the trace exporter agent.

--traces-exporter-port

If tracing is enabled, this port will be used to configure the trace exporter agent.

--metrics

If set, the sdk implementation of the OpenTelemetry metrics will be available for default monitoring and custom measurements. Otherwise a no-op implementation will be provided.

Default: False

--metrics-exporter-host

If tracing is enabled, this hostname will be used to configure the metrics exporter agent.

--metrics-exporter-port

If tracing is enabled, this port will be used to configure the metrics exporter agent.

auth#

jina auth [-h] {login, logout, token} ...

Positional Arguments#

auth_cli: Possible choices: login, logout, token

Sub-commands:#

logout#

Logout from Jina AI Ecosystem

jina auth logout [-h]

token#

Commands for Personal Access Token

jina auth token [-h] {create, delete, list} ...

Positional Arguments#

operation: Possible choices: create, delete, list

Sub-commands:#

create#

Create a Personal Access Token

jina auth token create [-h] [-e] name

Positional Arguments#

name: Name of Personal Access Token

Named Arguments#

-e, --expire

Validity period (days)

Default: 7

delete#

Revoke a Personal Access Token

jina auth token delete [-h] name

Positional Arguments#

name: Name of Personal Access Token which you want to delete

list#

List all Personal Access Tokens

jina auth token list [-h]

hub#

Push/Pull an Executor to/from Jina Hub

jina hub [-h] {new, push, pull, status ... 1 more choices} ...

subcommands#

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

hub_cli

Possible choices: new, push, pull, status, list

Manage Executor on Jina Hub

Sub-commands:#

new#

Create a new executor using the template

jina hub new [-h] [--name] [--path] [--advance-configuration] [--description]
             [--keywords] [--url]
             [--dockerfile {cpu, tf-gpu, torch-gpu, jax-gpu}]

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

--url

the URL of your GitHub repo

--dockerfile

Possible choices: cpu, tf-gpu, torch-gpu, jax-gpu

The Dockerfile template to use for the Executor

push#

Push an executor package to Jina hub

jina hub push [-h] [--no-usage] [--verbose] [-f DOCKERFILE] [-t]
              [--protected-tag] [--force-update] [--build-env] [--secret]
              [--no-cache] [--public | --private]
              path

Named Arguments#

--no-usage

If set, Hub executor usage will not be printed.

Default: False

--verbose

If set, more information will 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 jinaai[+docker]://<username>/MyExecutor:gpu

--protected-tag

A list of protected tags. Like tag but protected against updates after first push.

--force-update, --force

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

--build-env

A list of environment variables. It will be used in project build phase.

--secret

The secret for overwrite a Hub executor

--no-cache

If set, “–no-cache” option will be added to the Docker build.

Default: False

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-update] uri

Positional Arguments#

uri: The URI of the executor to pull (e.g., jinaai[+docker]://<username>/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-update, --force

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

Default: False

status#

Query an executor building status of of a pushed Executor from Jina hub

jina hub status [-h] [--id] [--verbose] [--replay] [path]

Status arguments#

path

The Executor folder to be pushed to Jina Hub.

Default: .

--id

If set, you can get the specified building state of a pushed Executor.

--verbose

If set, more building status information of a pushed Executor will be printed.

Default: False

--replay

If set, history building status information of a pushed Executor will be printed.

Default: False

list#

List your local Jina Executors

jina hub list [-h]

cloud#

Manage Flows on Jina Cloud

jina cloud [-h] [-v] [--loglevel {DEBUG, INFO, CRITICAL, NOTSET}]
           {login, deploy, list, logs ... 4 more choices} ...

Positional Arguments#

jc_cli: Possible choices: login, deploy, list, logs, status, remove, new, survey

Named Arguments#

-v, --version

Show version.

--loglevel

Possible choices: DEBUG, INFO, CRITICAL, NOTSET

Set the loglevel of the logger

Default: “INFO”

Sub-commands:#

login#

jina cloud login [-h]

deploy#

Deploy a Flow.

jina cloud deploy [-h] [--name] [--workspace] [--env-file] path

Positional Arguments#

path: The local path to a Jina flow project.

Named Arguments#

--name: If set, the URL of the flow will be prepended with this name.
--workspace: The string ID of a workspace. If set, re-use the given workspace instead of creating a new one.
--env-file: Pass the path to the local .env file.

list#

List all Flows.

jina cloud list [-h]
                [--status {SUBMITTED, NORMALIZING, NORMALIZED, STARTING ... 6 more choices}]

Named Arguments#

--status

Possible choices: SUBMITTED, NORMALIZING, NORMALIZED, STARTING, FAILED, ALIVE, UPDATING, DELETING, DELETED, ALL

Pass the status of Flows to be listed.

Default: ALIVE

logs#

Stream logs for a Flow.

jina cloud logs [-h] [--executor] flow

Positional Arguments#

flow: The string ID of a flow.

Named Arguments#

--executor: Pass name of the Executor to stream logs from.

status#

Get the status of a Flow.

jina cloud status [-h] flow

Positional Arguments#

flow: The string ID of a flow.

remove#

Remove Flow(s).

jina cloud remove [-h] [flows [flows ...]]

Positional Arguments#

flows: The string ID of a flow for single removal, or a list of space seperated string IDs for multiple removal, or string ‘all’ for deleting ALL ALIVE flows.

new#

Create a new Jina project via template.

jina cloud new [-h] path

Positional Arguments#

path

The new project will be created at this path.

Default: “helloworld”

survey#

Tell us your experience and help us improve.

jina cloud survey [-h]

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

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]
         [--timeout-ctrl] [--polling] [--shards] [--replicas] [--native]
         [--uses] [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
         [--uses-metas [KEY: VALUE [KEY: VALUE ...]]]
         [--uses-requests [KEY: VALUE [KEY: VALUE ...]]]
         [--uses-dynamic-batching [KEY: VALUE [KEY: VALUE ...]]]
         [--py-modules [PATH [PATH ...]]] [--output-array-type]
         [--exit-on-exceptions [[...]]] [--no-reduce]
         [--grpc-server-options [KEY: VALUE [KEY: VALUE ...]]] [--entrypoint]
         [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]]
         [--volumes [DIR [DIR ...]]] [--gpus] [--disable-auto-volume]
         [--host  [...]] [--runtime-cls] [--timeout-ready]
         [--env [KEY: VALUE [KEY: VALUE ...]]] [--floating] [--reload]
         [--install-requirements] [--port  [...]] [--monitoring]
         [--port-monitoring  [...]] [--retries] [--tracing]
         [--traces-exporter-host] [--traces-exporter-port] [--metrics]
         [--metrics-exporter-host] [--metrics-exporter-port] [--force-update]
         [--compression {NoCompression, Deflate, Gzip}]
         [--uses-before-address] [--uses-after-address] [--connection-list]
         [--timeout-send]

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: “default”

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

Scalable Deployment arguments#

--timeout-ctrl

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

Default: 60

--polling

The polling strategy of the Deployment and its endpoints (when shards>1). Can be defined for all endpoints of a Deployment or by endpoint. Define per Deployment: - ANY: only one (whoever is idle) Pod polls the message - ALL: all Pods poll the message (like a broadcast) Define per Endpoint: JSON dict, {endpoint: PollingType} {‘/custom’: ‘ALL’, ‘/search’: ‘ANY’, ‘*’: ‘ANY’}

Default: “ANY”

--shards

The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/concepts/flow/create-flow/#complex-flow-topologies

Default: 1

--replicas

The number of replicas in the deployment

Default: 1

--native

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

Default: False

WorkerRuntime arguments#

--uses

The config of the executor, it could be one of the followings: * the string literal of an Executor class name * 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

--uses-dynamic-batching

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

--py-modules

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

--output-array-type

The type of array tensor and embedding will be serialized to.

--exit-on-exceptions

List of exceptions that will cause the Executor to shut down.

Default: []

--no-reduce, --disable-reduce

Disable the built-in reduction mechanism. Set this if the reduction is to be handled by the Executor itself by operating on a docs_matrix or docs_map

Default: False

--grpc-server-options

Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1}

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/

--volumes

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

--gpus

This argument allows dockerized Jina Executors to 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

--disable-auto-volume

Do not automatically mount a volume for dockerized Executors.

Default: False

RemoteRuntime arguments#

--host, --host-in

Default: [‘0.0.0.0’]

Pod arguments#

--runtime-cls

The runtime class to run inside the Pod

Default: “WorkerRuntime”

--timeout-ready

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

Default: 600000

--env

The map of environment variables that are available inside runtime

--floating

If set, the current Pod/Deployment can not be further chained, and the next .add() will chain after the last Pod/Deployment not this current one.

Default: False

--reload

Default: False

--install-requirements

If set, try to install requirements.txt from the local Executor if exists in the Executor folder. If using Hub, install requirements.txt in the Hub Executor bundle to local.

Default: False

--port, --port-in

Default: [51030]

--monitoring

If set, spawn an http server with a prometheus endpoint to expose metrics

Default: False

--port-monitoring

The port on which the prometheus server is exposed, default is a random port between [49152, 65535]

Default: [51198]

--retries

Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)

Default: -1

--tracing

Default: False

--traces-exporter-host

If tracing is enabled, this hostname will be used to configure the trace exporter agent.

--traces-exporter-port

If tracing is enabled, this port will be used to configure the trace exporter agent.

--metrics

If set, the sdk implementation of the OpenTelemetry metrics will be available for default monitoring and custom measurements. Otherwise a no-op implementation will be provided.

Default: False

--metrics-exporter-host

If tracing is enabled, this hostname will be used to configure the metrics exporter agent.

--metrics-exporter-port

If tracing is enabled, this port will be used to configure the metrics exporter agent.

Pull arguments#

--force-update, --force

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

Default: False

Head arguments#

--compression

Possible choices: NoCompression, Deflate, Gzip

The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.

--uses-before-address

The address of the uses-before runtime

--uses-after-address

The address of the uses-before runtime

--connection-list

dictionary JSON with a list of connections to configure

--timeout-send

The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default

deployment#

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

jina deployment [-h] [--name] [--workspace] [--log-config] [--quiet]
                [--quiet-error] [--timeout-ctrl] [--polling] [--shards]
                [--replicas] [--native] [--uses]
                [--uses-with [KEY: VALUE [KEY: VALUE ...]]]
                [--uses-metas [KEY: VALUE [KEY: VALUE ...]]]
                [--uses-requests [KEY: VALUE [KEY: VALUE ...]]]
                [--uses-dynamic-batching [KEY: VALUE [KEY: VALUE ...]]]
                [--py-modules [PATH [PATH ...]]] [--output-array-type]
                [--exit-on-exceptions [[...]]] [--no-reduce]
                [--grpc-server-options [KEY: VALUE [KEY: VALUE ...]]]
                [--entrypoint] [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]]
                [--volumes [DIR [DIR ...]]] [--gpus] [--disable-auto-volume]
                [--host  [...]] [--runtime-cls] [--timeout-ready]
                [--env [KEY: VALUE [KEY: VALUE ...]]] [--floating] [--reload]
                [--install-requirements] [--port  [...]] [--monitoring]
                [--port-monitoring  [...]] [--retries] [--tracing]
                [--traces-exporter-host] [--traces-exporter-port] [--metrics]
                [--metrics-exporter-host] [--metrics-exporter-port]
                [--force-update]
                [--compression {NoCompression, Deflate, Gzip}]
                [--uses-before-address] [--uses-after-address]
                [--connection-list] [--timeout-send] [--uses-before]
                [--uses-after] [--when [KEY: VALUE [KEY: VALUE ...]]]
                [--external] [--grpc-metadata [KEY: VALUE [KEY: VALUE ...]]]
                [--tls]

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: “default”

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

Scalable Deployment arguments#

--timeout-ctrl

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

Default: 60

--polling

The polling strategy of the Deployment and its endpoints (when shards>1). Can be defined for all endpoints of a Deployment or by endpoint. Define per Deployment: - ANY: only one (whoever is idle) Pod polls the message - ALL: all Pods poll the message (like a broadcast) Define per Endpoint: JSON dict, {endpoint: PollingType} {‘/custom’: ‘ALL’, ‘/search’: ‘ANY’, ‘*’: ‘ANY’}

Default: “ANY”

--shards

The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/concepts/flow/create-flow/#complex-flow-topologies

Default: 1

--replicas

The number of replicas in the deployment

Default: 1

--native

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

Default: False

WorkerRuntime arguments#

--uses

The config of the executor, it could be one of the followings: * the string literal of an Executor class name * 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

--uses-dynamic-batching

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

--py-modules

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

--output-array-type

The type of array tensor and embedding will be serialized to.

--exit-on-exceptions

List of exceptions that will cause the Executor to shut down.

Default: []

--no-reduce, --disable-reduce

Disable the built-in reduction mechanism. Set this if the reduction is to be handled by the Executor itself by operating on a docs_matrix or docs_map

Default: False

--grpc-server-options

Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1}

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/

--volumes

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

--gpus

This argument allows dockerized Jina Executors to 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

--disable-auto-volume

Do not automatically mount a volume for dockerized Executors.

Default: False

RemoteRuntime arguments#

--host, --host-in

Default: [‘0.0.0.0’]

Pod arguments#

--runtime-cls

The runtime class to run inside the Pod

Default: “WorkerRuntime”

--timeout-ready

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

Default: 600000

--env

The map of environment variables that are available inside runtime

--floating

If set, the current Pod/Deployment can not be further chained, and the next .add() will chain after the last Pod/Deployment not this current one.

Default: False

--reload

Default: False

--install-requirements

If set, try to install requirements.txt from the local Executor if exists in the Executor folder. If using Hub, install requirements.txt in the Hub Executor bundle to local.

Default: False

--port, --port-in

Default: [58011]

--monitoring

If set, spawn an http server with a prometheus endpoint to expose metrics

Default: False

--port-monitoring

The port on which the prometheus server is exposed, default is a random port between [49152, 65535]

Default: [61418]

--retries

Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)

Default: -1

--tracing

Default: False

--traces-exporter-host

If tracing is enabled, this hostname will be used to configure the trace exporter agent.

--traces-exporter-port

If tracing is enabled, this port will be used to configure the trace exporter agent.

--metrics

If set, the sdk implementation of the OpenTelemetry metrics will be available for default monitoring and custom measurements. Otherwise a no-op implementation will be provided.

Default: False

--metrics-exporter-host

If tracing is enabled, this hostname will be used to configure the metrics exporter agent.

--metrics-exporter-port

If tracing is enabled, this port will be used to configure the metrics exporter agent.

Pull arguments#

--force-update, --force

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

Default: False

Head arguments#

--compression

Possible choices: NoCompression, Deflate, Gzip

The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.

--uses-before-address

The address of the uses-before runtime

--uses-after-address

The address of the uses-before runtime

--connection-list

dictionary JSON with a list of connections to configure

--timeout-send

The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default

Deployment arguments#

--uses-before

The executor attached before the Pods described by –uses, typically before sending to all shards, accepted type follows –uses. This argument only applies for sharded Deployments (shards > 1).

--uses-after

The executor attached after the Pods described by –uses, typically used for receiving from all shards, accepted type follows –uses. This argument only applies for sharded Deployments (shards > 1).

--when

The condition that the documents need to fulfill before reaching the Executor.The condition can be defined in the form of a DocArray query condition <https://docarray.jina.ai/fundamentals/documentarray/find/#query-by-conditions>

--external

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

Default: False

--grpc-metadata

The metadata to be passed to the gRPC request.

--tls

If set, connect to deployment using tls encryption

Default: False

client#

Start a Python client that connects to a Jina Gateway

jina client [-h] [--proxy] [--host] [--port] [--tls] [--asyncio] [--tracing]
            [--traces-exporter-host] [--traces-exporter-port] [--metrics]
            [--metrics-exporter-host] [--metrics-exporter-port]
            [--protocol {GRPC, HTTP, WEBSOCKET}]

Named Arguments#

--asyncio

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

Default: False

--tracing

Default: False

--traces-exporter-host

If tracing is enabled, this hostname will be used to configure the trace exporter agent.

--traces-exporter-port

If tracing is enabled, this port will be used to configure the trace exporter agent.

--metrics

If set, the sdk implementation of the OpenTelemetry metrics will be available for default monitoring and custom measurements. Otherwise a no-op implementation will be provided.

Default: False

--metrics-exporter-host

If tracing is enabled, this hostname will be used to configure the metrics exporter agent.

--metrics-exporter-port

If tracing is enabled, this port will be used to configure the metrics exporter agent.

--protocol

Possible choices: GRPC, HTTP, WEBSOCKET

Communication protocol between server and client.

Default: GRPC

ClientGateway arguments#

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

--host, --host-in

The host of the Gateway, which the client should connect to, by default it is 0.0.0.0.

Default: “0.0.0.0”

--port

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

--tls

If set, connect to gateway using tls encryption

Default: False