Run GraphQL requests from CLI

Table of contents

• Prerequisites
• Write a GraphQL script file
• Enter the running container
• Execute the script
• Save output to a file
• Command line parameters
• Use in AWS
• Exit codes

Run a single GraphQL script from a file using the built-in CLI in CloudBeaver

Prerequisites

• make sure the server container is running
• have an API access token
• prepare a file with exactly one GraphQL operation, save it in any format (such as.json or .txt), and make sure the content is valid JSON

Tip: with Docker Compose, either mount the script file or a folder of scripts into the service container at startup, or copy the file into the running container.

Write a GraphQL script file

Create a JSON file with query, variables, and operationName. For schema details and more operations, see GraphQL API overview.

Example:

{
 "query": "mutation createConnection($projectId: ID!, $config: ConnectionConfig!) { connection: createConnection(projectId: $projectId, config: $config) { ...DatabaseConnection } } fragment DatabaseConnection on ConnectionInfo { id projectId name }",
 "variables": {
   "projectId": "g_GlobalConfiguration",
   "config": {
     "configurationType": "MANUAL",
     "credentials": { "userPassword": "qwe", "userName": "qwe" },
     "mainPropertyValues": { "host": "localhost", "port": "3306" },
     "networkHandlersConfig": [],
     "providerProperties": {},
     "driverId": "mysql-ee:mysql8",
     "name": "MySQL@localhost",
     "host": "localhost",
     "port": "3306",
     "databaseName": null,
     "authModelId": "native",
     "properties": {}
   }
 },
 "operationName": "createConnection"
}

For more ready-to-run examples, see the CloudBeaver graphql examples repository.

Enter the running container

Open a shell in the Compose service container:

docker compose exec <service_name> bash

List services, and get the container id for a service:

docker compose ps
docker compose ps -q <service_name>

Copy your script from the host into the service container:

docker cp /path/on/host/create-connection.json $(docker compose ps -q <service_name>):/<your_custom_directory>/create-connection.json

Tip: if you use the older v1 CLI, replace docker compose with docker-compose.

Execute the script

Run the command:

docker compose exec <service_name> ./cbvr.sh -gql \
  -input-file /<your_custom_directory>/create-connection.json \
  --access-token <api_token>

The command prints the GraphQL response to stdout in JSON, including data, and, if present, errors. If errors occur, the command returns a non-zero exit code.

Save output to a file

To save the GraphQL response to a file:

docker compose exec <service_name> ./cbvr.sh -gql \
  -input-file /<your_custom_directory>/create-connection.json \
  -output-file /opt/cloudbeaver/workspace/out.txt \
  --access-token <api_token>

Command line parameters

Option / Command	Applies to	Description
-gql	GraphQL	Runs a GraphQL request from a file
import-license	License import	Imports a license file into CloudBeaver. Learn more
--access-token <token> / -token <token>	GraphQL	API access token for authentication
-input-file <path>	Both	Path to the input file inside the container (.json, .txt, or license file)
-output-file <path>	GraphQL	Path to the file where the response is saved (optional). A safe writable path inside the container is /opt/cloudbeaver/workspace/.

Use in AWS

If you run CloudBeaver on AWS, do the same steps inside the instance: place the JSON file on the instance, then run the CLI there.

For connection and file transfer basics, see AWS documentation:

• connect to your Linux instance using SSH
• connect using EC2 Instance Connect
• transfer files with scp

Exit codes

When CloudBeaver finishes executing a command, it returns an exit code to indicate the result.

Code	Name	Description
-1	EXIT_CODE_CONTINUE	Indicates that the process continues running. You won’t normally see this code when running commands.
0	EXIT_CODE_OK	Command executed successfully.
1	EXIT_CODE_ERROR	A general error occurred during execution.
2	EXIT_CODE_ILLEGAL_ARGUMENTS	Invalid command line arguments were provided.