equinix · cprivitere · Mar 10, 2022 · Feb 24, 2022 · Feb 24, 2022 · Feb 25, 2022
diff --git a/docs/metal.md b/docs/metal.md
@@ -34,9 +34,9 @@ Command line interface for Equinix Metal
 * [metal hardware-reservation](metal_hardware-reservation.md)	 - Hardware reservation operations. Information on reserving hardware on Equinix Metal is available on https://metal.equinix.com/developers/docs/deploy/reserved/.
 * [metal init](metal_init.md)	 - Create a configuration file.
 * [metal ip](metal_ip.md)	 - IP address and subnet operations. For more information on IP addresses, subnets, and IP address reservations, visit https://metal.equinix.com/developers/docs/networking/ip-addresses/.
-* [metal metros](metal_metros.md)	 - Metro operations
-* [metal operating-systems](metal_operating-systems.md)	 - Operating system operations
-* [metal organization](metal_organization.md)	 - Organization operations
+* [metal metros](metal_metros.md)	 - Metro operations. For more information on Equinix Metal metros and availability, visit https://metal.equinix.com/developers/docs/locations/metros/.
+* [metal operating-systems](metal_operating-systems.md)	 - Operating system operations. For more information on which operating systems Equinix Metal offers, visit https://metal.equinix.com/developers/docs/operating-systems/supported/.
+* [metal organization](metal_organization.md)	 - Organization operations. For more information on Equinix Metal organizations, visit https://metal.equinix.com/developers/docs/accounts/organizations/.
 * [metal plan](metal_plan.md)	 - Plan operations. For more information on the different Equinix Metal plans, visit https://metal.equinix.com/developers/docs/servers/server-specs/.
 * [metal project](metal_project.md)	 - Project operations. For more information on Equinix Metal Projects, visit https://metal.equinix.com/developers/docs/accounts/projects/.
 * [metal ssh-key](metal_ssh-key.md)	 - SSH key operations. For more information on SSH keys, visit https://metal.equinix.com/developers/docs/accounts/ssh-keys/ in the Equinix Metal documentation.

diff --git a/docs/metal_metros.md b/docs/metal_metros.md
@@ -1,10 +1,10 @@
 ## metal metros
 
-Metro operations
+Metro operations. For more information on Equinix Metal metros and availability, visit https://metal.equinix.com/developers/docs/locations/metros/.
 
 ### Synopsis
 
-Metro operations: get
+Metro operations: get.
 
 ### Options
 
@@ -29,5 +29,5 @@ Metro operations: get
 ### SEE ALSO
 
 * [metal](metal.md)	 - Command line interface for Equinix Metal
-* [metal metros get](metal_metros_get.md)	 - Retrieves a list of available metros.
+* [metal metros get](metal_metros_get.md)	 - Retrieves a list of metros.
 
diff --git a/docs/metal_metros_get.md b/docs/metal_metros_get.md
@@ -1,19 +1,22 @@
 ## metal metros get
 
-Retrieves a list of available metros.
+Retrieves a list of metros.
 
 ### Synopsis
 
-Example:
-
-metal metros get
-
-
+Retrieves a list of metros available to the current user.
 
 ```
 metal metros get [flags]
 ```
 
+### Examples
+
+```
+  # Lists metros available to the current user:	
+  metal metros get
+```
+
 ### Options
 
 ```
@@ -36,5 +39,5 @@ metal metros get [flags]
 
 ### SEE ALSO
 
-* [metal metros](metal_metros.md)	 - Metro operations
+* [metal metros](metal_metros.md)	 - Metro operations. For more information on Equinix Metal metros and availability, visit https://metal.equinix.com/developers/docs/locations/metros/.
 
diff --git a/docs/metal_operating-systems.md b/docs/metal_operating-systems.md
@@ -1,10 +1,10 @@
 ## metal operating-systems
 
-Operating system operations
+Operating system operations. For more information on which operating systems Equinix Metal offers, visit https://metal.equinix.com/developers/docs/operating-systems/supported/.
 
 ### Synopsis
 
-Operating system operations: get
+Operating system operations: get.
 
 ### Options
 
@@ -29,5 +29,5 @@ Operating system operations: get
 ### SEE ALSO
 
 * [metal](metal.md)	 - Command line interface for Equinix Metal
-* [metal operating-systems get](metal_operating-systems_get.md)	 - Retrieves a list of available operating systems.
+* [metal operating-systems get](metal_operating-systems_get.md)	 - Retrieves a list of operating systems.
 
diff --git a/docs/metal_operating-systems_get.md b/docs/metal_operating-systems_get.md
@@ -1,16 +1,22 @@
 ## metal operating-systems get
 
-Retrieves a list of available operating systems.
+Retrieves a list of operating systems.
 
 ### Synopsis
 
-Example:
-  metal operating-systems get
+Retrieves a list of operating systems available to the current user. Response includes the operating system's slug, distro, version, and name.
 
 ```
 metal operating-systems get [flags]
 ```
 
+### Examples
+
+```
+  # Lists the operating systems available to the current user:
+  metal operating-systems get
+```
+
 ### Options
 
 ```
@@ -33,5 +39,5 @@ metal operating-systems get [flags]
 
 ### SEE ALSO
 
-* [metal operating-systems](metal_operating-systems.md)	 - Operating system operations
+* [metal operating-systems](metal_operating-systems.md)	 - Operating system operations. For more information on which operating systems Equinix Metal offers, visit https://metal.equinix.com/developers/docs/operating-systems/supported/.
 
diff --git a/docs/metal_organization.md b/docs/metal_organization.md
@@ -1,10 +1,10 @@
 ## metal organization
 
-Organization operations
+Organization operations. For more information on Equinix Metal organizations, visit https://metal.equinix.com/developers/docs/accounts/organizations/.
 
 ### Synopsis
 
-Organization operations: create, update, delete and get
+Organization operations: create, get, update, payment-methods, and delete.
 
 ### Options
 
@@ -29,9 +29,9 @@ Organization operations: create, update, delete and get
 ### SEE ALSO
 
 * [metal](metal.md)	 - Command line interface for Equinix Metal
-* [metal organization create](metal_organization_create.md)	 - Creates an organization
-* [metal organization delete](metal_organization_delete.md)	 - Deletes an organization
-* [metal organization get](metal_organization_get.md)	 - Retrieves an organization or list of organizations
-* [metal organization payment-methods](metal_organization_payment-methods.md)	 - Retrieves a list of payment methods for the organization
-* [metal organization update](metal_organization_update.md)	 - Updates an organization
+* [metal organization create](metal_organization_create.md)	 - Creates an organization.
+* [metal organization delete](metal_organization_delete.md)	 - Deletes an organization.
+* [metal organization get](metal_organization_get.md)	 - Retrieves a list of organizations or the details of the specified organization.
+* [metal organization payment-methods](metal_organization_payment-methods.md)	 - Retrieves a list of payment methods.
+* [metal organization update](metal_organization_update.md)	 - Updates the specified organization.
 
diff --git a/docs/metal_organization_create.md b/docs/metal_organization_create.md
@@ -1,28 +1,34 @@
 ## metal organization create
 
-Creates an organization
+Creates an organization.
 
 ### Synopsis
 
-Example:
+Creates a new organization with the current user as the organization's owner. 
 
-metal organization create -n [name]
+```
+metal organization create -n <name> [-d <description>] [-w <website_URL>] [-t <twitter_URL>] [-l <logo_URL>] [flags]
+```
 
-	
+### Examples
 
 ```
-metal organization create [flags]
+  # Creates a new organization named "it-backend-infra": 
+  metal organization create -n it-backend-infra
+
+  # Creates a new organization with name, website, and twitter:
+  metal organization create -n test-org -w www.metal.equinix.com -t https://twitter.com/equinixmetal 
 ```
 
 ### Options
 
 ```
-  -d, --description string   Description of the organization
+  -d, --description string   Description of the organization.
   -h, --help                 help for create
-  -l, --logo string          Logo URL]
-  -n, --name string          Name of the organization
-  -t, --twitter string       Twitter URL of the organization
-  -w, --website string       Website URL of the organization
+  -l, --logo string          A Logo image URL.]
+  -n, --name string          Name of the organization.
+  -t, --twitter string       Twitter URL of the organization.
+  -w, --website string       Website URL of the organization.
 ```
 
 ### Options inherited from parent commands
@@ -41,5 +47,5 @@ metal organization create [flags]
 
 ### SEE ALSO
 
-* [metal organization](metal_organization.md)	 - Organization operations
+* [metal organization](metal_organization.md)	 - Organization operations. For more information on Equinix Metal organizations, visit https://metal.equinix.com/developers/docs/accounts/organizations/.
 
diff --git a/docs/metal_organization_delete.md b/docs/metal_organization_delete.md
@@ -1,25 +1,33 @@
 ## metal organization delete
 
-Deletes an organization
+Deletes an organization.
 
 ### Synopsis
 
-Example:
-
-metal organization delete -i [organization_UUID]
+Deletes an organization. You can not delete an organization that contains projects or has outstanding charges. Only organization owners can delete an organization.
 
-
+```
+metal organization delete -i <organization_UUID> [flags]
+```
+
+### Examples
 
 ```
-metal organization delete [flags]
+  # Deletes an organization, with confirmation: 
+  metal organization delete -i 3bd5bf07-6094-48ad-bd03-d94e8712fdc8
+  >
+  ✔ Are you sure you want to delete organization 3bd5bf07-6094-48ad-bd03-d94e8712fdc8: y
+
+  # Deletes an organization, skipping confirmation:
+  metal organization delete -i 3bd5bf07-6094-48ad-bd03-d94e8712fdc8 -f
 ```
 
 ### Options
 
 ```
-  -f, --force                    Force removal of the organization
+  -f, --force                    Skips confirmation for the removal of the organization.
   -h, --help                     help for delete
-  -i, --organization-id string   UUID of the organization
+  -i, --organization-id string   The UUID of the organization.
 ```
 
 ### Options inherited from parent commands
@@ -38,5 +46,5 @@ metal organization delete [flags]
 
 ### SEE ALSO
 
-* [metal organization](metal_organization.md)	 - Organization operations
+* [metal organization](metal_organization.md)	 - Organization operations. For more information on Equinix Metal organizations, visit https://metal.equinix.com/developers/docs/accounts/organizations/.
 
diff --git a/docs/metal_organization_get.md b/docs/metal_organization_get.md
@@ -1,28 +1,30 @@
 ## metal organization get
 
-Retrieves an organization or list of organizations
+Retrieves a list of organizations or the details of the specified organization.
 
 ### Synopsis
 
-Example:
-
-To retrieve list of all available organizations:
-metal organization get
+Retrieves a list of organizations or the details of the specified organization. Details of an organization are only available to its members.
 
-To retrieve a single organization:
-metal organization get -i [organization-id]
+```
+metal organization get -i <organization_UUID> [flags]
+```
 
-	
+### Examples
 
 ```
-metal organization get [flags]
+  # Retrieves list of the current user's organizations:
+  metal organization get
+
+  # Retrieves details of an organization:
+  metal organization get -i 3bd5bf07-6094-48ad-bd03-d94e8712fdc8
 ```
 
 ### Options
 
 ```
   -h, --help                     help for get
-  -i, --organization-id string   UUID of the organization
+  -i, --organization-id string   The UUID of an organization.
 ```
 
 ### Options inherited from parent commands
@@ -41,5 +43,5 @@ metal organization get [flags]
 
 ### SEE ALSO
 
-* [metal organization](metal_organization.md)	 - Organization operations
+* [metal organization](metal_organization.md)	 - Organization operations. For more information on Equinix Metal organizations, visit https://metal.equinix.com/developers/docs/accounts/organizations/.
 
diff --git a/docs/metal_organization_payment-methods.md b/docs/metal_organization_payment-methods.md
@@ -1,24 +1,27 @@
 ## metal organization payment-methods
 
-Retrieves a list of payment methods for the organization
+Retrieves a list of payment methods.
 
 ### Synopsis
 
-Example:
-
-metal organization payment-methods --id [organization_UUID]
+Retrieves a list of payment methods for the specified organization if the current user is a member with the proper role.
 
+```
+metal organization payment-methods -i <organization_UUID> [flags]
+```
 
+### Examples
 
 ```
-metal organization payment-methods [flags]
+  # Lists the payment methods for an organization:
+  metal organization payment-methods --id 3bd5bf07-6094-48ad-bd03-d94e8712fdc8
 ```
 
 ### Options
 
 ```
   -h, --help        help for payment-methods
-  -i, --id string   UUID of the organization
+  -i, --id string   The UUID of the organization.
 ```
 
 ### Options inherited from parent commands
@@ -37,5 +40,5 @@ metal organization payment-methods [flags]
 
 ### SEE ALSO
 
-* [metal organization](metal_organization.md)	 - Organization operations
+* [metal organization](metal_organization.md)	 - Organization operations. For more information on Equinix Metal organizations, visit https://metal.equinix.com/developers/docs/accounts/organizations/.
 
diff --git a/docs/metal_organization_update.md b/docs/metal_organization_update.md
@@ -1,29 +1,32 @@
 ## metal organization update
 
-Updates an organization
+Updates the specified organization.
 
 ### Synopsis
 
-Example:
-
-metal organization update --id [organization_UUID] --name [new_name]
+Updates the specified organization. You can update the name, website, Twitter, or logo.
 
+```
+metal organization update -i <organization_UUID> [-n <name>] [-d <description>] [-w <website_URL>] [-t <twitter_URL>] [-l <logo_URL>] [flags]
+```
 
+### Examples
 
 ```
-metal organization update [flags]
+  # Updates the name of an organization:
+  metal organization update -i 3bd5bf07-6094-48ad-bd03-d94e8712fdc8 --name test-cluster02
 ```
 
 ### Options
 
 ```
-  -d, --description string   Description of the organization
+  -d, --description string   User-friendly description of the organization.
   -h, --help                 help for update
-  -i, --id string            Organization ID
-  -l, --logo string          Logo URL of the organization
-  -n, --name string          Name of the organization
-  -t, --twitter string       Twitter URL of the organization
-  -w, --website string       Website of the organization
+  -i, --id string            An organization UUID.
+  -l, --logo string          A logo image URL for the organization.
+  -n, --name string          New name for the organization.
+  -t, --twitter string       A Twitter URL of the organization.
+  -w, --website string       A website URL for the organization.
 ```
 
 ### Options inherited from parent commands
@@ -42,5 +45,5 @@ metal organization update [flags]
 
 ### SEE ALSO
 
-* [metal organization](metal_organization.md)	 - Organization operations
+* [metal organization](metal_organization.md)	 - Organization operations. For more information on Equinix Metal organizations, visit https://metal.equinix.com/developers/docs/accounts/organizations/.