1.. _module-pw_software_update-cli: 2 3--------------------------------- 4pw_software_update: CLI reference 5--------------------------------- 6.. pigweed-module-subpage:: 7 :name: pw_software_update 8 9Overview 10--------- 11 12Use the ``pw_software_update`` CLI to quickly learn and prototype a software 13update system on your development PC before productionizing one. In the future 14you will be able to use the CLI to update a reference 15target. 16 17.. code-block:: bash 18 19 ~$ cd pigweed 20 ~/pigweed$ source ./activate.sh 21 ~/pigweed$ pw update [-h] <command> 22 23.. csv-table:: 24 :header: "Command", "Description" 25 :widths: 30, 70 26 :align: left 27 28 ``generate-key``, "generates a local signing key" 29 ``create-root-metadata``, "creates a TUF root metadata file" 30 ``sign-root-metadata``, "signs a TUF root metadata" 31 ``inspect-root-metadata``, "prints a TUF root metadata" 32 ``create-empty-bundle``, "creates an empty update bundle" 33 ``add-root-metadata-to-bundle``, "adds a root metadata to an existing bundle" 34 ``add-file-to-bundle``, "adds a target file to an existing bundle" 35 ``sign-bundle``, "signs an update bundle" 36 ``inspect-bundle``, "prints an update bundle" 37 ``verify-bundle``, "verifies an update bundle" 38 39generate-key 40------------ 41 42Generates an ECDSA SHA-256 public + private keypair. 43 44.. code-block:: bash 45 46 $ pw update generate-key [-h] pathname 47 48.. csv-table:: 49 :header: "Argument", "Description" 50 :widths: 30, 70 51 :align: left 52 53 ``pathname``, "output pathname for the new key pair" 54 55create-root-metadata 56-------------------- 57 58Creates a root metadata. 59 60.. code-block:: bash 61 62 $ pw update create-root-metadata [-h] 63 [--version VERSION] \ 64 --append-root-key ROOT_KEY \ 65 --append-targets-key TARGETS_KEY \ 66 -o/--out OUT 67 68.. csv-table:: 69 :header: "Option", "Description" 70 :widths: 30, 70 71 :align: left 72 73 ``--append-root-key``, "path to root key (public)" 74 ``--append-targets-key``, "path to targets key (public)" 75 ``--out``, "output path of newly created root metadata" 76 ``--version``, "anti-rollback version number of the root metadata (defaults to 1)" 77 78sign-root-metadata 79------------------ 80 81Signs a given root metadata. 82 83.. code-block:: bash 84 85 $ pw update sign-root-metadata [-h] \ 86 --root-metadata ROOT_METADATA \ 87 --root-key ROOT_KEY 88 89.. csv-table:: 90 :header: "Option", "Description" 91 :widths: 30, 70 92 :align: left 93 94 ``--root-metadata``, "Path of root metadata to be signed" 95 ``--root-key``, "Path to root signing key (private)" 96 97inspect-root-metadata 98--------------------- 99 100Prints the contents of a given root metadata. 101 102.. code-block:: bash 103 104 $ pw update inspect-root-metadata [-h] pathname 105 106.. csv-table:: 107 :header: "Argument", "Description" 108 :widths: 30, 70 109 :align: left 110 111 ``pathname``, "Path to root metadata" 112 113create-empty-bundle 114------------------- 115 116Creates an empty update bundle. 117 118.. code-block:: bash 119 120 $ pw update create-empty-bundle [-h] \ 121 [--target-metadata-version VERSION] \ 122 pathname 123 124.. csv-table:: 125 :header: "Argument", "Description" 126 :widths: 30, 70 127 :align: left 128 129 ``pathname``, "Path to newly created empty bundle" 130 131.. csv-table:: 132 :header: "Option", "Description" 133 :widths: 30, 70 134 :align: left 135 136 ``--target-metadata-version``, "Version number for targets metadata, defaults to 1" 137 138add-root-metadata-to-bundle 139--------------------------- 140 141Adds a root metadata to a bundle. 142 143.. code-block:: bash 144 145 $ pw update add-root-metadata-to-bundle [-h] \ 146 --append-root-metadata ROOT_METADATA \ 147 --bundle BUNDLE 148 149.. csv-table:: 150 :header: "Option", "Description" 151 :widths: 30, 70 152 :align: left 153 154 ``--append-root-metadata``, "Path to root metadata" 155 ``--bundle``, "Pathname of the bundle" 156 157 158add-file-to-bundle 159------------------ 160 161Adds a target file to an existing bundle. 162 163.. code-block:: bash 164 165 $ pw update add-file-to-bundle [-h] \ 166 [--new-name NEW_NAME] \ 167 --bundle BUNDLE \ 168 --file FILE_PATH 169 170.. csv-table:: 171 :header: "Option", "Description" 172 :widths: 30, 70 173 :align: left 174 175 ``--file``, "Path to a target file" 176 ``--bundle``, "Pathname of the bundle" 177 ``--new-name``, "Optional new name for target" 178 179sign-bundle 180----------- 181 182Signs an existing bundle with a dev key. 183 184.. code-block:: bash 185 186 $ pw update sign-bundle [-h] --bundle BUNDLE --key KEY 187 188.. csv-table:: 189 :header: "Option", "Description" 190 :widths: 30, 70 191 :align: left 192 193 ``--key``, "The targets signing key (private)" 194 ``--bundle``, "Pathname of the bundle" 195 196inspect-bundle 197-------------- 198 199Prints the contents of a given bundle. 200 201.. code-block:: bash 202 203 $ pw update inspect-bundle [-h] pathname 204 205.. csv-table:: 206 :header: "Argument", "Description" 207 :widths: 30, 70 208 :align: left 209 210 ``pathname``, "Pathname of the bundle" 211 212verify-bundle 213------------- 214 215Performs verification of an existing bundle. 216 217.. code-block:: bash 218 219 $ pw update verify-bundle [-h] \ 220 --bundle BUNDLE 221 --trusted-root-metadata ROOT_METADATA 222 223.. csv-table:: 224 :header: "Option", "Description" 225 :widths: 30, 70 226 227 ``--trusted-root-metadata``, "Trusted root metadata(anchor)" 228 ``--bundle``, "Pathname of the bundle to be verified" 229