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.

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>¶: Tuple of expected output file and is-executeable flag.

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

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

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