jama-cli 0.1.4

Command-line interface for Jama requirements management with MCP server support

Jama CLI

A powerful command-line interface for Jama requirements management, with MCP (Model Context Protocol) server support for AI assistants.

DISCLAIMER: This is an unofficial community project and is not associated with, endorsed by, or affiliated with Jama Software in any way.

Quick Start

# Install
pip install jama-cli

# Configure
jama config init

# Use
jama projects list
jama items list 123
jama items get 456 --output json

Features

CLI Commands

• Projects: List, view, and search projects
• Items: Full CRUD operations (create, read, update, delete)
• Relationships: Manage upstream/downstream traceability
• Traceability: Coverage analysis, trace matrix, trace trees
• Baselines: Compare baselines, view versioned items
• History: View item version history, compare versions
• Search: Full-text and regex search across projects
• Diff: Compare projects, count differences
• Migrate: Export, import, clone, copy data
• Types: View item types and their fields
• Config: Multi-profile configuration management

See EXAMPLES.md for comprehensive usage examples

MCP Server

• stdio mode: Native integration with Claude Desktop, Cline, VS Code
• HTTP mode: REST API with OpenAPI documentation
• 70 Jama operations: Complete API coverage

Output Formats

jama items list 123                    # Table (default)
jama items list 123 --output json      # JSON
jama items list 123 --output csv       # CSV
jama items list 123 --output yaml      # YAML

Installation

pip (recommended)

pip install jama-cli

pipx (isolated)

pipx install jama-cli

From source

git clone https://github.com/XORwell/jama-cli.git
cd jama-cli
pip install -e .

Configuration

Interactive Setup

jama config init

Configuration File

Location: ~/.jama/config.yml

default_profile: production

profiles:
  production:
    url: https://company.jamacloud.com
    auth_type: api_key
    api_key: ${JAMA_API_KEY}  # Environment variable

  staging:
    url: https://staging.jamacloud.com
    auth_type: oauth
    client_id: ${JAMA_CLIENT_ID}
    client_secret: ${JAMA_CLIENT_SECRET}

defaults:
  output: table
  limit: 50

Environment Variables

export JAMA_URL=https://company.jamacloud.com
export JAMA_API_KEY=your-api-key
export JAMA_PROFILE=production  # Optional: override default profile

CLI Commands

Projects

jama projects list                     # List all projects
jama projects get 123                  # Get project details
jama projects list --output json       # JSON output

Items

jama items list 123                    # List items in project 123
jama items get 456                     # Get item details
jama items children 456                # Get child items

# Create item
jama items create 123 --type 45 --name "New Requirement"

# Update item
jama items update 456 --name "Updated Name"
jama items update 456 --field status=Approved

# Delete item
jama items delete 456
jama items delete 456 --force          # Skip confirmation

Relationships

jama relationships list 456            # All relationships for item
jama relationships upstream 456        # Upstream items (traced from)
jama relationships downstream 456      # Downstream items (traced to)

# Create relationship
jama relationships create --from 456 --to 789

# Delete relationship  
jama relationships delete 123

Item Types

jama types list                        # List all item types
jama types get 45                      # Get type details

Configuration

jama config init                       # Interactive setup
jama config list                       # List profiles
jama config show                       # Show current profile
jama config add prod --url https://... --api-key xxx
jama config remove staging
jama config set-default production
jama config cache                      # Show cache stats
jama config cache --clear              # Clear cache

Search

jama search items "login"                        # Search all projects
jama search items "login" --project 123          # Search in specific project
jama search items "REQ-" --field documentKey     # Search by document key
jama search items "^REQ-\\d+" --regex            # Regex search
jama search items "test" --type 45               # Search specific item type
jama search fields 123                           # List searchable fields

Diff (Compare Projects)

jama diff projects 123 456                       # Compare two projects
jama diff projects 123 456 --from dev --to prod  # Compare across instances
jama diff projects 123 456 --type 45             # Compare specific item type
jama diff projects 123 456 --key name            # Match by name instead of key
jama diff count 123 456                          # Quick count comparison

Traceability Analysis

jama trace matrix 1172                           # Traceability matrix
jama trace matrix 1172 -s 45 -t 67               # Requirements → Test Cases
jama trace matrix 1172 --untraced                # Show coverage gaps
jama trace coverage 1172                         # Coverage % by item type
jama trace tree 12345                            # Trace tree for item
jama trace tree 12345 --direction upstream       # Upstream only

Baselines

jama baseline list 1172                          # List baselines
jama baseline items 100                          # Items in baseline
jama baseline diff 100 101                       # Compare baselines
# Shows: +Added, ~Modified, -Removed

Version History

jama history list 12345                          # Version history
jama history get 12345 3                         # Get version 3
jama history diff 12345 1 3                      # Compare versions

Data Migration

# Export items to JSON (fast by default)
jama migrate export 123                          # Export all items
jama migrate export 123 --max 100                # Export first 100 items (fast)
jama migrate export 123 --parent 456 --max 50   # Export subtree, limit 50
jama migrate export 123 --type 45                # Export only type 45
jama migrate export 123 --relationships          # Include relationships (slower)

# Import from JSON
jama migrate import backup.json --project 456   # Import to project 456
jama migrate import backup.json -p 456 --dry-run  # Preview import

# Clone within same instance
jama migrate clone 123 456                       # Clone project 123 to 456
jama migrate clone 123 456 --source-parent 789   # Clone children of item

# Copy between instances (requires two profiles)
jama migrate copy 123 456 --from staging --to production

# Inspect export file
jama migrate info backup.json

MCP Server

For Claude Desktop / Cline

Add to your MCP configuration:

{
  "mcpServers": {
    "jama": {
      "command": "jama",
      "args": ["serve", "--stdio"]
    }
  }
}

HTTP Server

# Start HTTP server
jama serve                             # Default: localhost:8000
jama serve --port 9000                 # Custom port
jama serve --api-key secret            # With authentication

# Access
curl http://localhost:8000/health
open http://localhost:8000/api/docs    # Swagger UI

Available Operations

The MCP server exposes 70 Jama API operations:

Category	Operations
Projects	get_projects, get_project
Items	get_items, get_item, create_item, update_item, delete_item
Relationships	get_relationships, create_relationship, delete_relationship
Types	get_item_types, get_item_type
Pick Lists	get_pick_lists, get_pick_list, get_pick_list_options
Tags	get_tags, get_tagged_items
Tests	get_test_plans, get_test_cycles, get_test_runs
Attachments	get_attachments, upload_attachment
...	See full list in API documentation

Global Options

jama [OPTIONS] COMMAND [ARGS]

Options:
  -p, --profile TEXT     Profile name from config
  -o, --output FORMAT    Output: table, json, csv, yaml
  -v, --verbose          Increase verbosity (-v, -vv, -vvv)
  -q, --quiet            Suppress non-error output
  --version              Show version
  --help                 Show help

Examples

List requirements and export to CSV

jama items list 123 --type 45 --output csv > requirements.csv

Get item as JSON for scripting

ITEM=$(jama items get 456 --output json)
echo $ITEM | jq '.fields.name'

Create item from script

jama items create 123 \
  --type 45 \
  --name "REQ-001: User Authentication" \
  --description "Users shall authenticate with SSO" \
  --field priority=High \
  --field status=Draft

Trace upstream requirements

jama relationships upstream 456 --output table

Use different profile

jama -p staging items list 123

Docker

A pre-built Docker image is available for running the Jama MCP server without installing Python.

docker pull ghcr.io/xorwell/jama-cli

Quick Start

# Using environment variables
docker run -p 8000:8000 \
  -e JAMA_URL=https://company.jamacloud.com \
  -e JAMA_API_KEY=your-api-key \
  ghcr.io/xorwell/jama-cli

The server starts on port 8000 with health checks, rate limiting, and Swagger UI at /api/docs.

Using a Config File

Mount your existing ~/.jama/config.yml into the container:

docker run -p 8000:8000 \
  -v ~/.jama/config.yml:/home/appuser/.jama/config.yml:ro \
  ghcr.io/xorwell/jama-cli

To use a specific profile from your config:

docker run -p 8000:8000 \
  -v ~/.jama/config.yml:/home/appuser/.jama/config.yml:ro \
  ghcr.io/xorwell/jama-cli \
  jama serve --host 0.0.0.0 --port 8000 --profile production

Authentication Methods

# API Key
docker run -p 8000:8000 \
  -e JAMA_URL=https://company.jamacloud.com \
  -e JAMA_API_KEY=your-api-key \
  ghcr.io/xorwell/jama-cli

# OAuth2 Client Credentials
docker run -p 8000:8000 \
  -e JAMA_URL=https://company.jamacloud.com \
  -e JAMA_CLIENT_ID=your-client-id \
  -e JAMA_CLIENT_SECRET=your-client-secret \
  ghcr.io/xorwell/jama-cli

# Username/Password
docker run -p 8000:8000 \
  -e JAMA_URL=https://company.jamacloud.com \
  -e JAMA_USERNAME=your-username \
  -e JAMA_PASSWORD=your-password \
  ghcr.io/xorwell/jama-cli

Server Authentication

Protect the MCP server with an API key so only authorized clients can use it:

docker run -p 8000:8000 \
  -e JAMA_URL=https://company.jamacloud.com \
  -e JAMA_API_KEY=your-jama-key \
  -e MCP_API_KEY=my-server-secret \
  ghcr.io/xorwell/jama-cli

# Clients must include: Authorization: Bearer my-server-secret

Docker Compose

services:
  jama-mcp:
    image: ghcr.io/xorwell/jama-cli
    ports:
      - "8000:8000"
    environment:
      - JAMA_URL=https://company.jamacloud.com
      - JAMA_API_KEY=${JAMA_API_KEY}
    # Or mount config:
    # volumes:
    #   - ~/.jama/config.yml:/home/appuser/.jama/config.yml:ro
    restart: unless-stopped

Using the CLI via Docker

You can also use the Docker image to run CLI commands:

docker run --rm \
  -e JAMA_URL=https://company.jamacloud.com \
  -e JAMA_API_KEY=your-api-key \
  ghcr.io/xorwell/jama-cli \
  jama projects list

docker run --rm \
  -e JAMA_URL=https://company.jamacloud.com \
  -e JAMA_API_KEY=your-api-key \
  ghcr.io/xorwell/jama-cli \
  jama items list 123 --output json

Building Locally

docker build -t jama-cli .
docker run -p 8000:8000 -e JAMA_URL=... -e JAMA_API_KEY=... jama-cli

See DOCKER.md for full Docker documentation including endpoints, image details, Kubernetes probes, and more.

Development

# Clone
git clone https://github.com/XORwell/jama-cli.git
cd jama-cli

# Install with dev dependencies
poetry install

# Run tests
poetry run pytest

# Lint
poetry run ruff check .
poetry run black --check .

# Type check
poetry run mypy jama_cli jama_mcp_server

License

MIT License - see LICENSE

Contributing

Contributions welcome! Please read CONTRIBUTING.md.

Related

• Jama REST API Documentation
• Model Context Protocol
• py-jama-rest-client