メインコンテンツへスキップ

list-commitments 

dci list-commitments [flags]

Returns a list of commitments for the customer. Commitments are listed in reverse chronological order by default.

CLI default view

dci list-commitments presents a curated table by default:

  • Columns: name, provider (from cloudProvider), commitment, attainment, and forecast (from totalCommitmentValue, totalCurrentAttainment, and totalForecastValue, all with the commitment's currency symbol), plus start and end dates.
  • --output json and explicit -C/--fields selections return the raw fields documented below.

Examples​

# Your commitments, newest first.
dci list-commitments
# Google Cloud commitments only, ending soonest first.
dci list-commitments --filter provider:google-cloud --sort-by endDate --sort-order asc
# Every page as JSON, for scripts.
dci list-commitments --all --output json

Flags​

FlagTypeDefaultExampleDescription
--sort-bystringA field by which the results will be sorted. One of: "name", "startDate", "endDate", "provider", "createTime", "updateTime".
--sort-orderstringSpecifies the sort direction; accepts asc for ascending (lowest to highest) or desc for descending (highest to lowest). One of: "asc", "desc".
--max-resultsinteger (int64)50The maximum number of results to return in a single page. Use the page tokens to iterate through the entire collection.
--page-tokenstringPage token, returned by a previous call, to request the next page of results
--filterstringprovider:google-cloudAn expression for filtering the results. The syntax is key:[<value>]. Multiple filters can be connected using a pipe |. See Filters. Available filter keys: name, provider

Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.

Output​

OK - The request succeeded.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
pageTokenstringPage token. It is used to request a specific page of the list results.
rowCountinteger (int64)The number of returned records.
commitmentsarray of objectArray of commitments.
commitments[].idstringThe unique identifier of the commitment.
commitments[].namestringThe name of the commitment.
commitments[].startDatestring (date-time)The start date of the commitment.
commitments[].endDatestring (date-time)The end date of the commitment.
commitments[].currencystringThe currency of the commitment.
commitments[].cloudProviderstringThe cloud provider associated with the commitment. One of: "google-cloud", "amazon-web-services", "microsoft-azure".
commitments[].totalCommitmentValuenumber (double)The total value of the commitment across all periods.
commitments[].totalCurrentAttainmentnumber (double)The total attained spend across all periods, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments. Rollover between periods is excluded, so excess or shortfall carried into a later period is not counted again; each period's carried amount is reported separately in periods[].rolloverFromPrevPeriod. Equals the sum of periods[].cashAttainment.
commitments[].totalMarketplaceSpendnumber (double)The total marketplace spend across all periods.
commitments[].totalForecastValuenumber (double)The total projected spend at the end of the commitment, summed across all periods. 0 when insufficient history is available to compute a forecast.
commitments[].periodsarray of objectThe list of commitment periods.
commitments[].periods[].startDatestring (date-time)The start date of the period.
commitments[].periods[].endDatestring (date-time)The end date of the period.
commitments[].periods[].commitmentValuenumber (double)The commitment value for this period.
commitments[].periods[].marketplaceLimitPercentagenumber (double)The marketplace limit as a percentage (0-100).
commitments[].periods[].marketplaceSpendnumber (double)The marketplace spend within this period.
commitments[].periods[].marketplaceLimitAmountnumber (double)The marketplace limit in absolute currency for this period, derived as commitmentValue * marketplaceLimitPercentage / 100.
commitments[].periods[].forecastValuenumber (double)The projected spend at the end of this period, based on a linear regression over the period's total spend series. 0 when insufficient history is available to compute a forecast.
commitments[].periods[].cashAttainmentnumber (double)This period's own attained spend, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments, excluding anything carried in from the previous period. Summed across periods it equals totalCurrentAttainment. To measure the period against its commitmentValue the way the console does, use cashAttainment + rolloverFromPrevPeriod + shortfallRollover; the period's remaining amount is commitmentValue minus that. Excess carried out to the next period is not deducted from this period.
commitments[].periods[].rolloverFromPrevPeriodnumber (double)The amount carried into this period from the previous period under the commitment's rollover terms. Positive for excess rollover, negative for shortfall rollover, 0 when nothing was carried (always 0 for the first period). amazon-web-services commitments no longer roll over, so this is 0 for them unless the commitment was last calculated before that change. Not included in cashAttainment or totalCurrentAttainment.
commitments[].periods[].shortfallRollovernumber (double)The part of this period's shortfall carried forward to the next period under the commitment's shortfall rollover terms, where it appears as a negative rolloverFromPrevPeriod. 0 when nothing was carried forward, including while the period is still open and for the last period. The console counts this amount as met within this period. Not included in cashAttainment or totalCurrentAttainment.
commitments[].createTimeinteger (int64)The creation time in milliseconds since epoch.
commitments[].updateTimeinteger (int64)The last update time in milliseconds since epoch.
Raw JSON schema
{
  "type": "object",
  "description": "List of commitments.",
  "properties": {
    "pageToken": {
      "type": "string",
      "description": "Page token. It is used to request a specific page of the list results.",
      "example": "bDl0QkEwVFZxUEwxaUJRaHhTcXM"
    },
    "rowCount": {
      "type": "integer",
      "description": "The number of returned records.",
      "format": "int64",
      "example": 1
    },
    "commitments": {
      "type": "array",
      "description": "Array of commitments.",
      "items": {
        "type": "object",
        "description": "Summary information of a commitment in a list.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The unique identifier of the commitment."
          },
          "name": {
            "type": "string",
            "description": "The name of the commitment."
          },
          "startDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-03-10T23:00:00Z",
            "description": "The start date of the commitment."
          },
          "endDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-03-10T23:00:00Z",
            "description": "The end date of the commitment."
          },
          "currency": {
            "type": "string",
            "description": "The currency of the commitment.",
            "example": "USD"
          },
          "cloudProvider": {
            "type": "string",
            "description": "The cloud provider associated with the commitment.",
            "enum": [
              "google-cloud",
              "amazon-web-services",
              "microsoft-azure"
            ]
          },
          "totalCommitmentValue": {
            "type": "number",
            "format": "double",
            "description": "The total value of the commitment across all periods."
          },
          "totalCurrentAttainment": {
            "type": "number",
            "format": "double",
            "description": "The total attained spend across all periods, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments. Rollover between periods is excluded, so excess or shortfall carried into a later period is not counted again; each period's carried amount is reported separately in `periods[].rolloverFromPrevPeriod`. Equals the sum of `periods[].cashAttainment`."
          },
          "totalMarketplaceSpend": {
            "type": "number",
            "format": "double",
            "description": "The total marketplace spend across all periods."
          },
          "totalForecastValue": {
            "type": "number",
            "format": "double",
            "description": "The total projected spend at the end of the commitment, summed across all periods. 0 when insufficient history is available to compute a forecast."
          },
          "periods": {
            "type": "array",
            "description": "The list of commitment periods.",
            "items": {
              "type": "object",
              "description": "A single period within a commitment.",
              "properties": {
                "startDate": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2024-03-10T23:00:00Z",
                  "description": "The start date of the period."
                },
                "endDate": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2024-03-10T23:00:00Z",
                  "description": "The end date of the period."
                },
                "commitmentValue": {
                  "type": "number",
                  "format": "double",
                  "description": "The commitment value for this period."
                },
                "marketplaceLimitPercentage": {
                  "type": "number",
                  "format": "double",
                  "description": "The marketplace limit as a percentage (0-100)."
                },
                "marketplaceSpend": {
                  "type": "number",
                  "format": "double",
                  "description": "The marketplace spend within this period."
                },
                "marketplaceLimitAmount": {
                  "type": "number",
                  "format": "double",
                  "description": "The marketplace limit in absolute currency for this period, derived as commitmentValue * marketplaceLimitPercentage / 100."
                },
                "forecastValue": {
                  "type": "number",
                  "format": "double",
                  "description": "The projected spend at the end of this period, based on a linear regression over the period's total spend series. 0 when insufficient history is available to compute a forecast."
                },
                "cashAttainment": {
                  "type": "number",
                  "format": "double",
                  "description": "This period's own attained spend, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments, excluding anything carried in from the previous period. Summed across periods it equals `totalCurrentAttainment`. To measure the period against its `commitmentValue` the way the console does, use `cashAttainment + rolloverFromPrevPeriod + shortfallRollover`; the period's remaining amount is `commitmentValue` minus that. Excess carried out to the next period is not deducted from this period."
                },
                "rolloverFromPrevPeriod": {
                  "type": "number",
                  "format": "double",
                  "description": "The amount carried into this period from the previous period under the commitment's rollover terms. Positive for excess rollover, negative for shortfall rollover, 0 when nothing was carried (always 0 for the first period). amazon-web-services commitments no longer roll over, so this is 0 for them unless the commitment was last calculated before that change. Not included in `cashAttainment` or `totalCurrentAttainment`."
                },
                "shortfallRollover": {
                  "type": "number",
                  "format": "double",
                  "description": "The part of this period's shortfall carried forward to the next period under the commitment's shortfall rollover terms, where it appears as a negative `rolloverFromPrevPeriod`. 0 when nothing was carried forward, including while the period is still open and for the last period. The console counts this amount as met within this period. Not included in `cashAttainment` or `totalCurrentAttainment`."
                }
              }
            }
          },
          "createTime": {
            "type": "integer",
            "format": "int64",
            "description": "The creation time in milliseconds since epoch."
          },
          "updateTime": {
            "type": "integer",
            "format": "int64",
            "description": "The last update time in milliseconds since epoch."
          }
        }
      }
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
50040API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: listcommitments