Command Reference

Core commands

handoff.core.admin.artifacts_archive(project_dir: str, workspace_dir: str, **kwargs) → None

handoff artifacts archive -p <project_directory>

Copy the artifacts directory from (remote) last to (remote) runs/<date>.

handoff.core.admin.artifacts_delete(project_dir: str, workspace_dir: str, **kwargs) → None

handoff artifacts delete -p <project_directory>

Delete artifacts from the remote artifacts/last directory

handoff.core.admin.artifacts_get(project_dir: str, workspace_dir: str, **kwargs) → None

handoff artifacts archive -p <project_directory> -w <workspace_directory>

Download artifacts from the (remote) last to <workspace_dir>

handoff.core.admin.artifacts_push(project_dir: str, workspace_dir: str, **kwargs) → None

handoff artifacts push -p <project_directory> -w <workspace_directory>

Push local artifacts file to remote storage under last directory.

handoff.core.admin.config_delete(project_dir: str, workspace_dir: str, **kwargs) → None

handoff config delete -p <project_directory> Delete the project configuration from the remote parameter store.

handoff.core.admin.config_deleteold(project_dir: str, workspace_dir: str, **kwargs) → None

handoff config delete -p <project_directory> Delete the project configuration from the remote parameter store.

handoff.core.admin.config_print(project_dir: str, workspace_dir: str, **kwargs) → None

handoff config print -p <project_directory> Print the project configuration in the remote parameter store.

handoff.core.admin.config_push(project_dir: str, workspace_dir: str, **kwargs) → None

handoff config push -p <project_directory> Push project.yml and the contents of project_dir/config as a secure parameter key.

handoff.core.admin.config_validate_local(project_dir: str, workspace_dir: str, **kwargs) → None

handoff config validate local -p <project_directory> Validate local configuration.

handoff.core.admin.files_delete(project_dir: str, workspace_dir: str, **kwargs) → None

handoff files delete -p <project_directory> Delete files and templates from the remote storage

handoff.core.admin.files_get(project_dir: str, workspace_dir: str, **kwargs) → None

handoff files get -p <project_directory> -w <workspace_directory> Download remote files to <workspace_dir>/files It also parse the templates with secrets and populate under <workspace_dir>/files

handoff.core.admin.files_get_local(project_dir: str, workspace_dir: str, **kwargs) → None

handoff files get local -p <project_directory> -w <workspace_directory> Copy files from the local project_dir to workspace_dir.

It also parse the templates with secrets and populate under <workspace_dir>/files

Any existing files in workspace_dir will be deleted.

handoff.core.admin.files_push(project_dir: str, workspace_dir: str, **kwargs) → None

handoff files push -p <project_directory> Push the contents of <project_dir>/files and <project_dir>/templates to remote storage.

The bucket and path format is: - bucket name: <account-id>-(dev-)<resource-name> - path: <task-name>/<path>

handoff.core.admin.project_delete(project_dir: str, workspace_dir: str, **kwargs) → None

handoff project push -p <project_directory> Push config, files, secrets all together

handoff.core.admin.project_push(project_dir: str, workspace_dir: str, **kwargs) → None

handoff project push -p <project_directory> Push config, files, secrets all together

handoff.core.admin.secrets_delete(project_dir: str, workspace_dir: str, yes: bool = False, **kwargs)

handoff secrets delete -p <project_directory> -d file=<secrets_file>

Delete the contents of <secrets_file> to remote parameter store By default, .secrets/secrets.yml in the current working directory is searched for the list of the secrets.

handoff.core.admin.secrets_print(project_dir: str, workspace_dir: str, **kwargs)

handoff secrets print -p <project_directory>

Get the secrets in the remote parameter store and dump in YAML format.

handoff.core.admin.secrets_push(project_dir: str, workspace_dir: str, yes: bool = None, **kwargs) → None

handoff secrets push -p <project_directory> -v secrets_dir=<secrets_dir>

Push the contents of <secrets_file> to remote parameter store

–vars secrets_dir (.secrets): The directory containing secrets.yml file, which is a YAML file storing secrets with format: ``` - key: key1

value: value1

  • key: key2 # The value can also be loaded from a text file file: file_name # The value is stored as a resource group level secret and can be # shared among the projects under the same group. level: “resource group”

```

The secrets are stored in the remote parameter store in the format: - /(dev-)<resource-group-name>/<task-name>/<parameter-name>

handoff.core.admin.version(project_dir: str, workspace_dir: str, **kwargs) → None

Print handoff version

handoff.core.admin.workspace_init(project_dir: str, workspace_dir: str, **kwargs) → None
handoff.core.admin.workspace_install(project_dir: str, workspace_dir: str, **kwargs) → None

handoff workspace install -p <project_directory> -w <workspace_directory> Install dependencies in the local virtual environment

handoff.core.task.run(config: Dict, **kwargs) → None

handoff run -w <workspace_directory> -e resource_group=<resource_group_name> task=<task_name> Run the task by the configurations and files stored in the remote parameter store and the file store.

handoff.core.task.run_local(config, **kwargs)

handoff run local -p <project_directory> -w <workspace_directory> Run the task locally.

handoff.core.task.shutdown(signal_id, from_)

Container commands

handoff.services.container.build(project_dir: str, workspace_dir: str, **kwargs) → None

handoff container build -p <project_directory> -v docker_file=<docker_file> files_dir=<addtnl_files_dir> Build the container image Optionally, use docker_file to specify own Dockerfile

handoff.services.container.bundle(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None
handoff.services.container.push(project_dir: str, workspace_dir: str, **kwargs) → None

handoff container push -p <project_directory> Push the container image to remote repository

handoff.services.container.run(project_dir: str, workspace_dir: str, **kwargs) → None

handoff container run -p <project_directory> -e resource_group=<resource_group_name> task=<task_name> __VARS=’key1=val1 key2=val2…’ Run the container

If the environment variable __VARS is specified via -e option, it will be used as: handoff run -d $(eval echo $__VARS)

On Mac, you probably need to do -v ‘platform=linux/x86_64’ unless Dockerfile specifies the platform.

If you do container build with a custom Dockerfile containing EXPOSE commands, you can bind the ports. You can bind port betwewn container’s 22 and 80 to host’s 2222 and 8080 by -v ‘ports={“22”:2222,”80”:8080}’ See https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.ContainerCollection.run

Cloud commands

handoff.services.cloud.bucket_create(project_dir: str, workspace_dir: str, **kwargs) → None

handoff cloud bucket create -p <project_directory> Create remote storage bucket. Bucket is attached to the resource group.

handoff.services.cloud.bucket_delete(project_dir: str, workspace_dir: str, **kwargs) → None

handoff cloud bucket delete -p <project_directory> Delete remote storage bucket.

handoff.services.cloud.bucket_status(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud bucket status -p <project_directory> -s <stage> Check the status of bucket

handoff.services.cloud.bucket_update(project_dir: str, workspace_dir: str, **kwargs) → None

handoff cloud bucket update -p <project_directory> Update remote storage bucket info

handoff.services.cloud.container_build(project_dir: str, workspace_dir: str, envs: Dict = {}, vars: Dict = {}, extras: str = None, yes: bool = False, **kwargs) → None

handoff cloud container build -v resource_group=<resource_group_name> task=<task_name> target_id=<target_id> -e vars=’key1=val1 key2=val2…’ build and push container in the cloud

handoff.services.cloud.container_version(project_dir: str, workspace_dir: str, envs: Dict = {}, vars: Dict = {}, extras: str = None, yes: bool = False, **kwargs) → None
handoff.services.cloud.domain_set(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud domain set -p <project_directory> -v hostedzone_id=<hostedzone_id> subdomain=<subdomain> list task status

AWS options: - full: When true, print the full description (default: false) - running: When true, include desired status = RUNNING (default: true) - stopped: When true, include desired status = STOPPED (default: true) - resource_group_level: When true, list all the tasks under the same resource groups (default: false)

handoff.services.cloud.get_platform(provider_name: str = None, platform_name: str = None, stdout: bool = False, cloud_profile: str = None, vars: Dict = {}, **kwargs) → ModuleType
handoff.services.cloud.job_status(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud job status -p <project_directory> -v full=False running=True stopped=True resource_group_level=False list task status

AWS options: - full: When true, print the full description (default: false) - running: When true, include desired status = RUNNING (default: true) - stopped: When true, include desired status = STOPPED (default: true) - resource_group_level: When true, list all the tasks under the same resource groups (default: false)

handoff.services.cloud.job_stop(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud job stop -p <project_directory> -v id=<task_id> reason=<reason> stop a running task Options: - reason

handoff.services.cloud.login_test(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None
handoff.services.cloud.logout()
handoff.services.cloud.logs(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud logs -v start_time=<start_time> end_time=<end_time> follow=<True/False> Show logs Use –vars (-v) option to: - start_time: ISO 8086 formatted date time to indicate the start time - end_time - follow: If set, it waits for more logs until interrupted by ctrl-c - filter: Filter log term

handoff.services.cloud.resources_create(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud resources create -p <project_directory> Create resources necessary for task execution. The resources are shared among the tasks under the same resource group.

Optionally: -v static_ip=True: [AWS] Create Elastic IP and NAT Gateway to obtain a static IP. This [costs more](https://aws.amazon.com/vpc/pricing/).

AWS: - Please refer to the

handoff.services.cloud.resources_delete(project_dir: str, workspace_dir: str, **kwargs) → None

handoff cloud resources delete -p <project_directory> Delete the resources

The resources are shared among the tasks under the same resource group.

handoff.services.cloud.resources_status(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud resources status -p <project_directory> -s <stage> Check the status of resources

handoff.services.cloud.resources_update(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud resources update -p <project_directory> Update the resources

The resources are shared among the tasks under the same resource group.

handoff.services.cloud.role_create(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud role create -p <project_directory> -v external_id=<id> grantee_account_id=<grantee_id> Create the role with deployment privilege.

handoff.services.cloud.role_delete(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud role delete -p <project_directory> -v grantee_account_id=<grantee_id> Delete the role.

handoff.services.cloud.role_status(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud role status -p <project_directory> -s <stage> Check the status of role

handoff.services.cloud.role_update(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud role update -p <project_directory> -v external_id=<id> grantee_account_id=<grantee_id> Update the role privilege information.

handoff.services.cloud.run(project_dir: str, workspace_dir: str, envs: Dict = {}, vars: Dict = {}, extras: str = None, **kwargs) → None

handoff cloud run -v resource_group=<resource_group_name> task=<task_name> target_id=<target_id> -e vars=’key1=val1 key2=val2…’ Run a task once in the platform

If the environment variable vars is specified via -e option, it will be used as: handoff run -v $(eval echo $vars)

handoff.services.cloud.schedule_create(project_dir: str, workspace_dir: str, envs: Dict = {}, vars: Dict = {}, extras: str = None, **kwargs) → None

handoff cloud schedule create -v target_id=<target_id> cron=”<cron_format>” -e vars=’key1=val1 key2=val2…’ Schedule a task named <target_id> at the recurring scheduled specified as <cron_format>. An example of cron-format string is 10 01 * * ? * for every day at 01:10 (1:10AM)

If the environment variable vars is specified via -e option, it will be used as: handoff run -v $(eval echo $vars)

handoff.services.cloud.schedule_delete(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud schedule delete -v target_id=<target_id> Unschedule a task named <target_id>

handoff.services.cloud.schedule_list(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud schedule list List the scheduled tasks

Use –vars (-v) option to: - scope: Controls how deployed EventBridge rules are matched to this

task. Rule names only differ from a sibling task’s rules (e.g. “foo” vs “foo-rest”) by a plain string prefix, so this choice matters: - declared (default): only rules whose target_id is already

declared in this project’s local schedules config. Safest; will not surface schedules that exist in AWS but were never declared locally.

  • prefix: legacy behavior, matches any rule whose name starts with this task’s stack name. Can over-match a sibling task whose name extends this one.

  • all: every handoff-managed schedule in the AWS account, regardless of task.

  • include_unpublished: also include locally declared schedules that have not been deployed yet.

handoff.services.cloud.task_create(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud task create -p <project_directory> Create the task Optionally, -v cpu=256 memory=512 storage=21 The above example is for AWS Fargate with vCPU 256 unit, 512MB memory, and 21GB ephemeral storage

handoff.services.cloud.task_delete(project_dir: str, workspace_dir: str, **kwargs) → None

handoff cloud task delete -p <project_directory> Delete the task

handoff.services.cloud.task_status(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud task status -p <project_directory> -s <stage> Check the status of task

handoff.services.cloud.task_update(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff cloud task update -p <project_directory> Update the task Optionally, -v cpu=256, memory=512

Envs commands

handoff.plugins.envs.get(project_dir: str, workspace_dir: str, vars: Dict = {}, **kwargs) → None

handoff envs get -p <project_dir> -d key=<env_var_key> Get the value of an evirohment varaible specified by <env_var_key>

Quick start commands

handoff.plugins.quick_start.make(project_dir: str, workspace_dir: str, **kwargs) → None

handoff quick_start make Copy the test projects to the test_projects under the current directory