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.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.vscode		.vscode
docs		docs
jama_cli		jama_cli
jama_mcp_server		jama_mcp_server
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
API_COVERAGE.md		API_COVERAGE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
COMPARISON.md		COMPARISON.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
EXAMPLES.md		EXAMPLES.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
ROADMAP.md		ROADMAP.md
config.yml.example		config.yml.example
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Jama CLI

Quick Start

Features

CLI Commands

MCP Server

Output Formats

Installation

pip (recommended)

pipx (isolated)

From source

Configuration

Interactive Setup

Configuration File

Environment Variables

CLI Commands

Projects

Items

Relationships

Item Types

Configuration

Search

Diff (Compare Projects)

Traceability Analysis

Baselines

Version History

Data Migration

MCP Server

For Claude Desktop / Cline

HTTP Server

Available Operations

Global Options

Examples

List requirements and export to CSV

Get item as JSON for scripting

Create item from script

Trace upstream requirements

Use different profile

Docker

Quick Start

Using a Config File

Authentication Methods

Server Authentication

Docker Compose

Using the CLI via Docker

Building Locally

Development

License

Contributing

Related

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages