./bai v2 CLI usage for testing/verifying API endpoints and managing resources — entity-command reference, login/config, search patterns, testing workflow (REST API client, NOT the v1 backend.ai CLI)
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
./bai v2 CLI usage for testing/verifying API endpoints and managing resources — entity-command reference, login/config, search patterns, testing workflow (REST API client, NOT the v1 backend.ai CLI)
tags
["cli","bai","testing","rest-api"]
./bai CLI Usage Guide
Guide for testing and verifying API endpoints and managing resources with the Backend.AI v2 CLI (./bai).
IMPORTANT:
./bai is the v2 REST API CLI. It is separate from the legacy v1 CLI (backend.ai / ./backend.ai).
Do NOT use v1 CLI commands. Do all testing and verification with ./bai.
Before running a ./bai command, confirm the command exists in the Entity-Command Reference below. No guessing or fabrication, no searching the CLI source.
Verify the command tree with --help (works without a server): ./bai {entity} --help, ./bai admin {entity} --help, ./bai my {entity} --help.
Each entity is marked by access level — user (user-facing) / admin (superadmin only) / my (own resources).
"(empty group)" is a placeholder group with no commands (example: ./bai agent is empty and the actual commands are under ./bai admin agent).
Check options with --help.
The session cookie is stored in ~/.backend.ai/session/cookie.dat.
Direct API (alternative)
Access the manager directly without the webserver (HMAC signature auth):
./bai config set endpoint http://127.0.0.1:8091
./bai config set endpoint-type api
./bai config set access-key AKIAIOSFODNN7EXAMPLE
./bai config set secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
./bai config show
The configuration is stored in ~/.backend.ai/config.toml and credentials.toml.
my — self-service (the current user's own resources)
Entity names are singular (domain, user, agent)
A sub-entity is a Click sub-group (revision, channel, role, etc.)
The standard 6 operations: create, get, search, update, delete, purge (only some, depending on the entity).
Special operations: enqueue/terminate (session), revision add/revision activate (deployment), login/logout.
CLI input style
Default: an individual --option flag per field.
Secondary: a JSON string or an @file path for complex nested structures (example: --initial-revision, --config).
Do NOT use raw JSON as a positional argument for create/update (with some admin command exceptions: admin domain create).
For get/delete/purge, use the entity identifier (UUID, name) as a positional argument.
Search patterns
# admin search — whole system (superadmin only)
./bai admin {entity} search --limit 5
# project-scoped search — the scope ID is a positional argument (not an option)
./bai {entity} project-search {project_id} --limit 5
# self-service search — own resources
./bai my {entity} search --limit 5
Options and filters differ per entity, so check with ./bai {entity} {command} --help.
--order-by syntax
Multi-sort with field:direction:
./bai admin user search --order-by created_at:desc --order-by username:asc
Naming conventions
The CLI --order-by maps to the DTO order field (common across all entities).
The CLI --kebab-case option maps to the DTO snake_case field (Click standard).
Scoped search: the scope ID is a positional argument, not a --scope-* option.
Raw GraphQL
./bai gql (not ./bai admin gql) sends a raw GraphQL query. Useful for testing GQL schema changes or when there is no REST CLI:
./bai config show # check endpoint-type
./bai login # log in if the session expired
After modifying server code
For local development, restart the service first — see the /local-dev skill.
# 1. confirm basic connectivity
./bai admin domain search --limit 1
./bai domain get default
# 2. test the modified entity (with the command matching its level)# if user-facing ./bai {entity} ..., if admin-only ./bai admin {entity} ...
./bai admin {entity} search --limit 1
./bai {entity} get {id}
# 3. test the permission boundary
./bai admin {entity} search # admin succeeds# after switching to a regular user, the same command → should fail with 403
After commands, verify the runtime behavior with the Grafana MCP — see /observability.
To catch errors not surfaced in the CLI response, check Loki ({service_name="manager"} |= "error");
to check the request count, look at Prometheus (backendai_api_request_count).
Testing as a regular user
The default accounts are in fixtures/manager/example-users.json.
# log in as a regular user session
BACKEND_USER=user@lablup.com BACKEND_PASSWORD=C8qnIo29 ./bai login
# should succeed (user-facing)
./bai domain get default
# should fail with 403 (admin only)
./bai admin domain search --limit 1
After testing, revert to the admin credentials.
Smoke test script
Run everything with admin credentials. OK if each command returns JSON.
