Aqua CLI

A command-line tool for Aqua Cloud — manage requirements, defects, and test cases from your terminal.

Designed for AI coding agents (Claude Code, Cursor, Copilot, Aider, Windsurf) and human developers alike. Any tool that can run shell commands can use Aqua CLI.

Why a CLI?

• Universal — every AI agent can run bash commands, not all support MCP
• Zero setup — npx @aqua-cloud/cli works instantly, no config files to edit
• Composable — pipe to jq, grep, xargs — Unix philosophy
• Compound operations — one command does what takes 3-4 MCP tool calls
• Scriptable — use in CI/CD, git hooks, shell scripts

Quick Start

Install

npm install -g @aqua-cloud/cli

# Or run directly without installing
npx @aqua-cloud/cli --help

Configure

# Interactive setup
aqua login

# Or via environment variables
export AQUA_URL=https://your-instance.aqua-cloud.io/aquaWebNG
export AQUA_USER=your-username
export AQUA_PASS=your-password
export AQUA_PROJECT_ID=123

# Or via CLI flags
aqua --url https://... --user admin --pass secret --project 123 list Requirement

Verify

aqua doctor

Configuration

Settings are resolved in priority order (highest wins):

1. CLI flags — --url, --user, --pass, --project
2. Environment variables — AQUA_URL, AQUA_USER, AQUA_PASS, AQUA_PROJECT_ID
3. Project file — .aqua.env in the current directory (git-ignored)
4. User config — ~/.aqua/config.json (created by aqua login)

OAuth tokens are cached to ~/.aqua/token.json to avoid re-authenticating on every invocation.

Commands

Items

aqua list <type>                          # List items (Requirement, Defect, TestCase, TestScenario)
aqua list Requirement --status "Draft"    # Filter by status
aqua list Defect --assigned-to "John"     # Filter by assignee
aqua list Defect --take 10               # Limit results

aqua get <ID>                             # Get item details (e.g., aqua get RQ123)
aqua get <ID> --brief                     # Brief: just title + status

aqua create <type> --title "..." --desc "..."          # Create an item
aqua create Requirement --title "Login" --parent RQ100 # Create sub-item

aqua status <ID> <status-name>            # Update status by name (auto-resolves to ID!)
aqua comment <ID> "message"               # Add a comment
aqua history <ID>                         # View change history
aqua link <ID1> <ID2>                     # Create relationship between items
aqua search "query"                       # Global search

Test Cases

aqua steps <TC-ID>                        # Get test steps
aqua add-steps <TC-ID> --file steps.json  # Add steps from JSON file
aqua add-steps <TC-ID> --stdin            # Add steps from stdin (pipe-friendly)

Projects

aqua projects                             # List all projects
aqua project                              # Show current project
aqua project <ID>                         # Switch to a project
aqua statuses <type>                      # List available statuses for a type

Compound Commands

These combine multiple API calls into single operations — the real value-add for AI agents.

# Full context dump: details + children + test cases + steps + history
aqua context <ID>

# Find an unassigned item and claim it
aqua pick <type> [--status "Ready"]

# Mark done + optional comment in one shot
aqua done <ID> -c "Implemented and all tests pass"

# Bulk create test cases with steps from a JSON file
aqua gen-tests <RQ-ID> --file tests.json

# Project dashboard with counts by status
aqua dashboard [--type Defect]

# Update multiple items to the same status at once
aqua bulk-status Done RQ123 RQ124 RQ125

Exchange (ReqIF / DOORS)

aqua export-reqif RQ123                   # Export a single item
aqua export-reqif RQ1,RQ2,RQ3            # Export specific items
aqua export-reqif --folder 42             # Export from specific folder
aqua export-reqif --all                   # Export all requirements
aqua export-reqif --all -o out.reqif      # Custom output path
aqua export-reqif --all --type Defect     # Export defects instead

aqua import-reqif doors-export.reqif      # Import items from ReqIF
aqua import-reqif export.reqif --preview  # Dry run — show parsed items
aqua import-reqif export.reqif --folder 42   # Import into specific folder
aqua import-reqif export.reqif --parent RQ100  # Create as sub-items
aqua import-reqif export.reqif --type Defect   # Import as defects

Export requires a scope — pass IDs (positional or --id), --folder, or --all. Import always needs a file path.

Utilities

aqua login                                # Interactive credential setup
aqua doctor                               # Check config and API connectivity
aqua cheatsheet                           # Concise reference card (great for AI agent context)

Output Formats

| Format | Flag | Description | |--------|------|-------------| | json | --format json or --json | Full JSON (default when piped) | | table | --format table | ASCII table (default in terminal) | | compact | --format compact | One line per item | | ids | --format ids | Just IDs, one per line (for piping) |

Output format is auto-detected: table when running in a terminal, json when output is piped to another command. Override with --format or --json.

Verbosity

aqua get RQ123                    # Standard detail
aqua get RQ123 --brief            # Title + status + ID only
aqua get RQ123 -v                 # All fields, relations, full text

Smart Features

Status by name

No need to look up numeric status IDs. The CLI resolves names automatically:

aqua status RQ123 Done            # Resolves "Done" → status ID 31586
aqua status RQ123 "In Progress"   # Handles multi-word statuses

Auto type inference

Item type is inferred from the ID prefix — no --type flag needed:

aqua get DF456                    # Knows it's a Defect
aqua get RQ123                    # Knows it's a Requirement
aqua get TC789                    # Knows it's a TestCase

Fuzzy ID parsing

All these work:

aqua get RQ123
aqua get RQ0123
aqua get 123 --type Requirement

Error Handling

Errors are structured JSON with actionable suggestions:

{
  "error": true,
  "code": "STATUS_NOT_FOUND",
  "message": "Status 'Dne' not found for Requirement",
  "suggestion": "Available statuses: Draft (ID: 31582), To Do (ID: 31583), ...",
  "command_hint": "aqua statuses Requirement"
}

Exit codes: 0 success, 1 user error, 2 auth error, 3 API error.

For AI Agents

Feed the cheatsheet to your AI agent at the start of a session:

aqua cheatsheet

This prints a concise reference of all commands with examples — enough context for any agent to work with Aqua Cloud effectively.

Install the skill into your coding agent

This package ships a ready-made rules/skill bundle that teaches your AI coding agent how to drive the Aqua CLI — commands, examples, and multi-step workflows. Install it for your agent of choice:

aqua install-skill            # Claude Code (default)
aqua install-skill cursor     # Cursor
aqua install-skill agents     # AGENTS.md — Codex, opencode, Amp, Jules, Pi, Devin, …
aqua install-skill --list     # show every supported agent and its target path

Supported agents: claude, cursor, windsurf, cline, roo, continue, trae, kiro, augment, junie, antigravity, copilot, gemini, goose, zed, agents (with aliases codex, opencode, amp, jules, pi, devin).

Scope. By default the skill installs to the agent's user-level location so it applies across all your projects. Use --local to write it into the current repository instead (so it can be committed and shared with your team), or --global to force the user-level location:

aqua install-skill gemini             # ~/.gemini/GEMINI.md (global, default)
aqua install-skill gemini --local     # ./GEMINI.md (this project, committable)
aqua install-skill cursor             # ./.cursor/rules/aqua-cloud.mdc (no global location, so project-local)

A few agents have no user-level file (Cursor, Windsurf, Trae, Copilot) and the agents group reads a different global file per tool, so those install project-local. Shared instruction files (AGENTS.md, GEMINI.md, .goosehints, Zed's rules) are updated in place between managed markers — your existing content is never overwritten. The agent picks the skill up on its next session.

Example: pipe-friendly workflows

# Get all requirement IDs in Draft status
aqua list Requirement --status Draft --format ids

# Bulk update items piped from another command
aqua list Defect --status "Open" --format ids | xargs aqua bulk-status "In Progress"

# Get item details as JSON for further processing
aqua get RQ123 --json | jq '.Name'

gen-tests JSON Format

The gen-tests command expects a JSON file with this structure:

[
  {
    "title": "Login with valid credentials",
    "description": "Verify successful login flow",
    "steps": [
      {
        "name": "Enter credentials",
        "instructions": "Type username and password",
        "expectedResult": "Fields accept input"
      },
      {
        "name": "Click login",
        "instructions": "Click the login button",
        "expectedResult": "User is redirected to dashboard"
      }
    ]
  }
]

Requirements

• Node.js >= 20.6.0
• An aqua Cloud instance and a valid aqua subscription

Support

• Email: [email protected]
• Documentation: https://docs.aqua-cloud.io
• Website: https://aqua-cloud.io

License

Proprietary software. © 2026 aqua cloud GmbH. All rights reserved.

This package is licensed, not sold. Use is permitted only by customers with a valid aqua subscription and is governed by the LICENSE file and aqua's Terms & Conditions. Redistribution, modification, and reverse engineering are not permitted except as expressly allowed by that agreement.