doctl-balance

Get balance of the account associated with the current context

$ doctl balance [[g|get]]

$ doctl balance [[g|get]] [[-t|--access-token]] [access_token]

$ doctl balance [[g|get]] --context

doctl balance get [flags]

--access-token <token>
    Specifies a DigitalOcean API personal access token for authentication. Overrides any token set via doctl auth init or environment variables.

--config <path>
    Specifies a custom configuration file path for doctl. Default is usually ~/.config/doctl/config.yaml.

--format <columns>
    Columns to include in the output when using text format (e.g., 'ID,Name,Status'). Not directly applicable to balance get output as it's not a list of resources.

--no-header
    Prevents printing of table headers for text output. Also not directly applicable to balance get output which is a single record.

--output <format>
    Sets the output format. Supported formats include json, text, yaml, and csv. Defaults to text.

--trace
    Includes a tracing header in API requests, useful for debugging API calls and communication with DigitalOcean.

--verbose
    Enables verbose output, showing more details about command execution, including API request URLs.

The doctl balance get command is a crucial subcommand of the official DigitalOcean CLI client, doctl. It provides users with a direct and programmatic way to retrieve their current outstanding account balance, month-to-date usage, and any remaining account credit. This functionality is essential for monitoring cloud infrastructure spending, tracking resource consumption, and understanding billing cycles without needing to access the DigitalOcean control panel. The command's output, which can be formatted as JSON, text, or YAML, typically includes the current month's usage, total account balance, the timestamp of the last update, and the start and end dates of the current billing period. It integrates seamlessly into scripting and automation workflows for financial oversight.

The term 'doctl-balance' is often used conceptually to refer to the functionality provided by the doctl balance get command. It is not a standalone executable.
The command requires the doctl CLI to be installed and properly configured with a DigitalOcean API token that has read access to account information.
Balance information is subject to the update frequency of DigitalOcean's billing system and may not reflect real-time changes instantaneously.

The command you are asking about, often referred to as 'doctl-balance', is actually executed as doctl balance get. doctl is the main command-line interface for DigitalOcean, balance is a subcommand, and get is the specific action to retrieve balance information. This structure is common in modern CLIs where a single executable manages multiple related functionalities.

To successfully use doctl balance get, an active DigitalOcean API token is required. This token must have at least read access to account information. It can be configured globally using doctl auth init, which stores it securely, or passed directly with the --access-token flag for single-command execution or in environments where global configuration is not preferred.

The doctl CLI was developed by DigitalOcean to empower developers with a powerful command-line interface for managing their cloud resources. The balance subcommand, specifically its get action, has been a foundational component since the early stages of doctl's development. Its inclusion underscores DigitalOcean's commitment to transparency and providing users with direct access to critical billing and usage information, facilitating better financial management and integration into automated workflows.

doctl(1), curl(1), grep(1), jq(1)