Skip to content

gcube CLI — configure

View or change global CLI settings.

Configuration Management

gcube configure                              # Interactive setup (prompts appear in order)
gcube configure set --token <token>          # Save API token
gcube configure set --platform-url <URL>     # Change platform URL (default recommended)
gcube configure set --ws-url <URL>           # Change WebSocket URL (default recommended)
gcube configure set --output <format>        # Change default output format (table|json|yaml)
gcube configure get token                    # View saved token value
gcube configure get platform-url             # View platform URL
gcube configure get ws-url                   # View WebSocket URL
gcube configure get output                   # View current default output format
gcube configure status                       # Check current settings and token validity

Note

platform-url and ws-url are set to the official gcube server by default. There is no need to change them unless you are using a separate private environment.

Review Needed

Confirmation from the development team is needed on what platform-url and ws-url represent and how they are used.

The configuration file is saved at ~/.gcube/config.yaml.

platform_url: https://api.gcube.ai
ws_url: wss://console.gcube.ai:61443
auth:
  access_token: "eyJ..."
  expires_at: "2026-07-01T00:00:00Z"    # Token expiration time
output: table

Note

If your token expires, reissue a new token from the website and update it with gcube configure set --token <new token>. Running commands with an expired token will return exit code 3 (authentication failure).

Review Needed

The specific steps and path for reissuing a token need to be confirmed.

Output Format

You can specify the output format using the -o global option on any command.

gcube workload list               # table (default)
gcube -o json workload list       # JSON
gcube -o yaml workload list       # YAML
gcube -o json workload describe 2212 | jq '.state'

Note

jq in the example above is a separate CLI tool for filtering JSON. It must be installed beforehand.

  • macOS: brew install jq
  • Ubuntu/Debian: sudo apt install jq
  • Windows: Download from the jq official site

Review Needed

Whether jq needs to be pre-installed and how it integrates with gcube CLI should be confirmed.

To change the default output format, use the following command.

gcube configure set --output json

Environment Variables

Environment variables take precedence over the configuration file (environment variables > config file > defaults).

Variable Description
GCUBE_ACCESS_TOKEN Bearer token
GCUBE_PLATFORM_URL Platform API URL
GCUBE_OUTPUT Default output format (table|json|yaml)

Note

Environment variables are mainly used in CI/CD pipelines (GitHub Actions, GitLab CI, etc.) to securely pass tokens without exposing them directly in code. For local development, using gcube configure set --token is typical.

GitHub Actions usage example:

- name: Register workload
  env:
    GCUBE_ACCESS_TOKEN: ${{ secrets.GCUBE_TOKEN }}
    GCUBE_OUTPUT: json
  run: gcube workload register -f pipeline.yaml

Exit Codes

Code Meaning
0 Success
1 Invalid argument or state error
2 gcube API error
3 Authentication failure or token expired
4 Network error