---
name: ecommon-sh
description: Use when auditing or reusing the shared EDirect shell functions that other Entrez Direct wrapper scripts source internally.
disable-model-invocation: true
user-invocable: true
---

# ecommon-sh

Shared shell library for Entrez Direct wrappers. This file defines functions and global variables for argument parsing, retry logic, logging, and ENTREZ_DIRECT envelope handling. It is not a normal end-user CLI.

## Quick Start

- **Command:** `source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh`
- **Local file:** `/home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh`
- **Observed library version when sourced:** `24.0`

## When To Use This Tool

- Inspect the common behavior inherited by EDirect wrappers such as `ecollect`.
- Reuse shared shell functions like `ParseCommonArgs`, `FinishSetup`, `RunWithLogging`, and `WriteEDirect` in your own wrappers.
- Understand how EDirect normalizes flags, retries failed EUtils requests, and serializes ENTREZ_DIRECT metadata.
- Debug why multiple EDirect shell scripts share the same option handling, logging, or error-reporting behavior.

## Common Patterns

```bash
# 1) Source the library and inspect its version variable
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
printf '%s\n' "$version"
```

```bash
# 2) Minimal wrapper skeleton that reuses common flag parsing and setup
#!/usr/bin/env bash
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh

ParseCommonArgs "$@"
shift "$argsConsumed"
FinishSetup

RunWithLogging nquire -url "$base" einfo.fcgi -db pubmed
```

```bash
# 3) Emit an ENTREZ_DIRECT envelope after a wrapper finishes
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
WriteEDirect "pubmed" "$web_env" "$qry_key" "$num" "$stp" ""
```

## Recommended Workflow

1. Treat `ecommon.sh` as a library file and source it into a shell or wrapper script instead of executing it directly.
2. Call `ParseCommonArgs "$@"` first if you want the standard EDirect flags and remember to `shift "$argsConsumed"` before handling tool-specific options.
3. Run `FinishSetup` before network work so base URL, API key, email, and related globals are initialized consistently.
4. Reuse `RunWithLogging` / retry helpers and `WriteEDirect` rather than reimplementing that behavior piecemeal.

## Guardrails

- Running `bash ecommon.sh` or `bash ecommon.sh -version` is silently unhelpful in this environment: both paths exit with no useful output.
- The `24.0` version string is visible only after sourcing the file or through sibling wrappers that expose it.
- This library relies on mutable global state (`db`, `input`, `web_env`, `qry_key`, `verbose`, `tranquil`, and others). Source it into a clean shell context or isolate your wrapper logic carefully.
- Many helper functions eventually invoke sibling EDirect tools such as `xtract`, `transmute`, and `nquire`; sourcing the file does not guarantee those commands are on `PATH`.
- Autogenerated docs that treat `ecommon.sh` as a standalone command are misleading. The meaningful interface here is its function set, not its direct process invocation.