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