CLI reference

BuildGrid’s Command Line Interface (CLI) reference documentation.

bgd

BuildGrid’s client and server CLI front-end.

bgd [OPTIONS] COMMAND [ARGS]...

Commands

action-cache: Query and update the action cache service.

bot: Create and register bot clients.

browser-backend: bgd-browser backend API.

capabilities: Capabilities service.

cas: Interact with the CAS server.

cleanup: Start a local cleanup service.

execute: Execute simple operations.

logstream: LogStream commands.

operation: Long running operations commands.

server: Start a local server instance.

bgd action-cache

Entry-point for the bgd action-cache CLI command group.

bgd action-cache [OPTIONS] COMMAND [ARGS]...

Options

--remote <remote>

Remote execution server’s URL (port defaults to 50051 if no specified).

Default:: http://localhost:50051

--auth-token <auth_token>: Authorization token for the remote.

--client-key <client_key>: Private client key for TLS (PEM-encoded).

--client-cert <client_cert>: Public client certificate for TLS (PEM-encoded).

--server-cert <server_cert>: Public server certificate for TLS (PEM-encoded)

--instance-name <instance_name>: Targeted farm instance name.

--action-id <action_id>: Action ID.

--invocation-id <invocation_id>: Tool invocation ID.

--correlation-id <correlation_id>: Correlated invocation ID.

Commands

get: Retrieves a cached action-result.

update: Maps an action to a given action-result.

bgd action-cache get

Entry-point of the bgd action-cache get CLI command.

Note:: Digest strings are expected to be like: {hash}/{size_bytes}.

bgd action-cache get [OPTIONS] ACTION_DIGEST_STRING

Options

--json

Print action result in JSON format.

Default:: False

Arguments

ACTION_DIGEST_STRING: Required argument

bgd action-cache update

Entry-point of the bgd action-cache update CLI command.

Note:: Digest strings are expected to be like: {hash}/{size_bytes}.

bgd action-cache update [OPTIONS] ACTION_DIGEST_STRING
                        ACTION_RESULT_DIGEST_STRING

Arguments

ACTION_DIGEST_STRING: Required argument

ACTION_RESULT_DIGEST_STRING: Required argument

bgd bot

Create and register bot clients.

bgd bot [OPTIONS] COMMAND [ARGS]...

Options

--remote <remote>

Remote execution server’s URL (port defaults to 50051 if not specified).

Default:: http://localhost:50051

--auth-token <auth_token>: Authorization token for the remote.

--client-key <client_key>: Private client key for TLS (PEM-encoded).

--client-cert <client_cert>: Public client certificate for TLS (PEM-encoded).

--server-cert <server_cert>: Public server certificate for TLS (PEM-encoded).

--remote-cas <remote_cas>: Remote CAS server’s URL (port defaults to 11001 if not specified).

--cas-client-key <cas_client_key>: Private CAS client key for TLS (PEM-encoded).

--cas-client-cert <cas_client_cert>: Public CAS client certificate for TLS (PEM-encoded).

--cas-server-cert <cas_server_cert>: Public CAS server certificate for TLS (PEM-encoded).

--update-period <update_period>

Time period for bot updates to the server in seconds.

Default:: 30

--executing-update-period <executing_update_period>

Time period for bot updates to the server whilst execution is happening, in seconds.

Default:: 5

--instance-name <instance_name>: Server resource to target.

-w, --worker-property <worker_property>: List of key-value pairs of worker properties.

-v, --verbose: Increase log verbosity level.

Commands

dummy: Run a dummy session simply returning leases.

host-tools: Runs commands using the host’s tools.

bgd bot dummy

Creates a session, accepts leases, does fake work and updates the server.

bgd bot dummy [OPTIONS]

bgd bot host-tools

Downloads inputs from CAS, runs build commands using host-tools and uploads result back to CAS.

bgd bot host-tools [OPTIONS]

bgd cas

Entry point for the bgd-cas CLI command group.

bgd cas [OPTIONS] COMMAND [ARGS]...

Options

--remote <remote>

Remote execution server’s URL (port defaults to 50051 if no specified).

Default:: http://localhost:50051

--auth-token <auth_token>: Authorization token for the remote.

--client-key <client_key>: Private client key for TLS (PEM-encoded).

--client-cert <client_cert>: Public client certificate for TLS (PEM-encoded).

--server-cert <server_cert>: Public server certificate for TLS (PEM-encoded)

--instance-name <instance_name>: Targeted farm instance name.

--action-id <action_id>: Action ID.

--invocation-id <invocation_id>: Tool invocation ID.

--correlation-id <correlation_id>: Correlated invocation ID.

Commands

download-dir: Download a directory from the CAS server.

download-file: Download one or more files from the CAS server. (Specified as a space-separated list of DIGEST FILE_PATH)

upload-dir: Upload a directory to the CAS server.

upload-dummy: Upload a dummy action. Should be used with execute dummy-request

upload-file: Upload files to the CAS server.

bgd cas download-dir

Download a directory from the CAS server.

bgd cas download-dir [OPTIONS] DIGEST_STRING DIRECTORY_PATH

Options

--verify

Check downloaded directory’s integrity.

Default:: False

Arguments

DIGEST_STRING: Required argument

DIRECTORY_PATH: Required argument

bgd cas download-file

Download one or more files from the CAS server. (Specified as a space-separated list of DIGEST FILE_PATH)

bgd cas download-file [OPTIONS] DIGEST_PATH_LIST...

Options

--verify

Check downloaded file’s integrity.

Default:: False

Arguments

DIGEST_PATH_LIST: Required argument(s)

bgd cas upload-dir

Upload a directory to the CAS server.

bgd cas upload-dir [OPTIONS] DIRECTORY_PATH

Options

--verify

Check uploaded directory’s integrity.

Default:: False

Arguments

DIRECTORY_PATH: Required argument

bgd cas upload-file

Upload files to the CAS server.

bgd cas upload-file [OPTIONS] FILE_PATH...

Options

--verify

Check uploaded files integrity.

Default:: False

Arguments

FILE_PATH: Required argument(s)

bgd execute

Entry point for the bgd-execute CLI command group.

bgd execute [OPTIONS] COMMAND [ARGS]...

Options

--remote <remote>

Remote execution server’s URL (port defaults to 50051 if no specified).

Default:: http://localhost:50051

--auth-token <auth_token>: Authorization token for the remote.

--client-key <client_key>: Private client key for TLS (PEM-encoded).

--client-cert <client_cert>: Public client certificate for TLS (PEM-encoded).

--server-cert <server_cert>: Public server certificate for TLS (PEM-encoded).

--instance-name <instance_name>: Targeted farm instance name.

--remote-cas <remote_cas>: Remote CAS server’s URL (defaults to –remote if not specified).

--cas-client-key <cas_client_key>: Private CAS client key for TLS (PEM-encoded).

--cas-client-cert <cas_client_cert>: Public CAS client certificate for TLS (PEM-encoded).

--cas-server-cert <cas_server_cert>: Public CAS server certificate for TLS (PEM-encoded).

--action-id <action_id>: Action ID.

--invocation-id <invocation_id>: Tool invocation ID.

--correlation-id <correlation_id>: Correlated invocation ID.

Commands

command: Send a command to be executed.

request-dummy: Send a dummy action.

bgd execute command

Send a command to be executed.

bgd execute command [OPTIONS] INPUT_ROOT COMMANDS...

Options

--output-file <output_file>: Expected output file.

--output-directory <output_directory>

Output directory for the output files.

Default:: testing

-p, --platform-property <platform_property>: List of key-value pairs of required platform properties.

--disable-cancellation: By default, SIGINT sends a CancelOperation request. Set this flag to disable this behavior.

-c, --enable-action-cache: By default, the result is not cached and the cache isn’t checked for a previous result. Set this flag to enable caching.

--priority <priority>

Set priority of execution request, the value can be negative or positive. Smaller values result in higher priority.

Default:: 0

--request-workflow <request_workflow>: The workflow of execution request, e.g., build

--request-actor <request_actor>: The actor of execution request, e.g. bgd-cli

--request-subject <request_subject>: The subject of execution request, e.g. user1

Arguments

INPUT_ROOT: Required argument

COMMANDS: Required argument(s)

bgd execute request-dummy

Send a dummy action.

bgd execute request-dummy [OPTIONS]

Options

--number <number>

Number of request to send.

Default:: 1

--wait-for-completion: Stream updates until jobs are completed.

bgd operation

Entry point for the bgd-operation CLI command group.

bgd operation [OPTIONS] COMMAND [ARGS]...

Options

--remote <remote>

Remote execution server’s URL (port defaults to 50051 if no specified).

Default:: http://localhost:50051

--auth-token <auth_token>: Authorization token for the remote.

--client-key <client_key>: Private client key for TLS (PEM-encoded).

--client-cert <client_cert>: Public client certificate for TLS (PEM-encoded).

--server-cert <server_cert>: Public server certificate for TLS (PEM-encoded).

--instance-name <instance_name>: Targeted farm instance name.

--action-id <action_id>: Action ID.

--invocation-id <invocation_id>: Tool invocation ID.

--correlation-id <correlation_id>: Correlated invocation ID.

Commands

cancel: Cancel an operation.

list: List operations.

status: Get the status of an operation.

wait: Streams an operation until it is complete.

bgd operation list

List operations.

bgd operation list [OPTIONS]

Options

--json

Print operations list in JSON format.

Default:: False

--page-token <page_token>: Token to start from. Set this to the “next_page_token” of the previous ListOperationsResult to get the next page of results.

--page-size <page_size>: Number of operations to request per page. Cannot be larger than the server maximum (throws an error).

--filter-string, --filter <filter_string>: Filter which operations are returned. By default, only incomplete operations are shown. See docs for syntax.

bgd operation status

Get the status of an operation.

bgd operation status [OPTIONS] OPERATION_NAME

Options

--json

Print operations status in JSON format.

Default:: False

--show-request-metadata: Show RequestMetadata message

Arguments

OPERATION_NAME: Required argument

bgd operation wait

Streams an operation until it is complete.

bgd operation wait [OPTIONS] OPERATION_NAME

Options

--json

Print operations statuses in JSON format.

Default:: False

Arguments

OPERATION_NAME: Required argument

bgd server

Start a local server instance.

bgd server [OPTIONS] COMMAND [ARGS]...

Commands

start: Setup a new server instance.

bgd server start

Entry point for the bgd-server CLI command group.

bgd server start [OPTIONS] CONFIG

Options

-v, --verbose: Increase log verbosity level.

--pid-file <pid_file>: Path to PID file

Arguments

CONFIG: Required argument