🌾 Gather

In a Nutshell

Discover identifiers and candidate records from documents, URLs, or text with acorn gather <INPUT>.

Discover persistent identifiers in files, documents, URLs, standard input, and literal text.

Directory traversal

Directory inputs are searched recursively by default, including files in every descendant directory. When no input, --text, or standard input is supplied, gather recursively searches the current directory.

Use --max-depth to limit traversal. Direct children of an input directory have depth 1, grandchildren have depth 2, and so on. A depth of 0 processes no directory descendants but does not exclude explicitly supplied files.

# Search the complete directory tree
acorn gather path/to/project

# Search only files directly inside the directory
acorn gather path/to/project --max-depth 1

# Include one nested directory level
acorn gather path/to/project --max-depth 2

--filter and --ignore are applied to the paths found within the selected depth.

Other inputs

acorn gather report.docx
acorn gather --text "doi:10.1234/example"
printf 'https://ror.org/01qz5mb56' | acorn gather

Non-empty standard input is gathered automatically and can be combined with positional inputs. arXiv identifiers may use modern or legacy arXiv: forms or arxiv.org/abs/ and /pdf/ URLs. Remote URLs require network access. Global --offline mode rejects remote input and cannot be combined with --resolve.

Watch mode

Use the global --watch flag to run immediately and gather again only when effective source content changes:

acorn --watch gather path/to/project
acorn gather --watch --watch-mode poll https://example.org/report.json
acorn gather --watch --osti projects "ACORN"

--watch-mode auto uses native filesystem notifications for local-only inputs and polling for HTTP(S), resolved identifiers, DOE CODE searches, and merge-request selections. Use --watch-mode poll for network-mounted paths or environments where native events are unreliable. --poll-interval (-p) accepts durations such as 500ms or 5s. Press q or Ctrl+C to stop watching. Standard input cannot be replayed and is therefore rejected in watch mode; repeated --text values remain static inputs.

Output formats

Gather supports console, json, markdown, and yaml output. When --format is omitted, an interactive terminal receives a table containing only discoveries and remote provider matches; piped or file output uses JSON. Resolution checks are rendered separately using the same detailed format as acorn check. Use --terse to render compact checks without the discovery table. Warning and error states are visible by default, while -vv also shows informational transitions such as found, resolved, created, enriched, and unchanged.

Use --raw to print only the normalized identifiers, one per line, for piping to another command. Raw stdout remains machine-readable: check diagnostics are suppressed unless -v is present, and verbose diagnostics are written to stderr without a table. With --raw --resolve, arXiv and DOI lines become citations and ORCID lines become Given Family (https://orcid.org/...); other PID types retain their normalized form. Use --citation-format to select apa, chicago, harvard, ieee, mla, or vancouver. The CLI option takes precedence over ACORN_CITATION_FORMAT, and the default is IEEE. Unsupported environment values produce a warning and use IEEE; unsupported CLI values are rejected. Use -q or --quiet to suppress output.

acorn gather report.docx --format console
acorn gather report.docx --format yaml --output discoveries.yaml
acorn gather report.docx --terse
acorn gather report.docx --raw | sort -u
acorn gather report.docx --raw --resolve --citation-format apa

Resolved raw output remains machine-readable: successful values use one line each. Load or resolution failures retain a nonzero exit status; they are silent by default and are rendered to stderr when verbosity is enabled. A DOI without the selected citation style and an ORCID without public given/family or credit-name data falls back to its normalized identifier.

Research activity candidates

Unless global --no-local-database is set, ordinary gather appends every discovered identifier to discovery history and persists project-like discoveries as evolving research activity candidates. arXiv, DOI, RAiD, ISBN, patent, and ARK values can independently identify a candidate. arXiv revisions retain their versioned evidence but match the same unversioned candidate. ISNI, ORCID, ROR, PIDINST, unknown identifiers, and arbitrary URLs remain in the report and discovery history but do not create or merge candidates by themselves.

See the persistent identifier lifecycle for how ACORN finds, parses, validates, normalizes, classifies, and persists this evidence.

Candidates merge only when they share an exact normalized project identity. A new identity creates a row with a portable NanoID; one matching row gains missing fields and unique array values; repeated evidence is unchanged. Conflicting populated fields keep their stored value and record the observation as provenance. Evidence matching multiple rows is reported as a conflict without merging those rows.

Enrichment mapping

Enrichment is additive and evidence-driven. ACORN starts with the identifiers found locally or returned by the selected provider, calls only the resolvers applicable to that entity and URL, and maps explicitly asserted values into candidate fields. Identifiers are normalized before use; arrays are deduplicated; and websites are deduplicated by URL. Keywords and technologies are resolved to canonical values from ACORN’s embedded controlled vocabularies, including known aliases; values with no vocabulary match are omitted from the mapped candidate but remain in provider provenance when that source is persisted. At database persistence, a new scalar fills an empty field, while a conflict with an existing populated scalar preserves the stored value and records the new observation as provenance. Unmapped values are not coerced into unrelated fields. Failure of an optional ORCID, GitHub, or GitLab lookup leaves the original provider result intact.

RAiD organization classification is driven by the explicit organization role, not by the organization’s name. Funder maps to meta.sponsors; lead or other research organization, partner, contractor, facility, and other organization roles map to meta.partners. An organization carrying both funder and non-funder roles is represented in both lists. A single roleless organization is treated as the default lead organization and therefore as a partner; roleless entries in a multi-organization record are not classified. ACORN resolves a display name only when the ROR exists in its embedded sponsor or partner vocabulary. Otherwise, the normalized ROR remains in meta.ror without an invented name.

The persistent identifier lifecycle describes field precedence, identity matching, CFF intake, and provenance in more detail. JSON and YAML reports include each persisted candidate’s iid and action, plus created, enriched, unchanged, and conflicts totals under summary.candidates.

# Discover identifiers without writing discovery history or candidates
acorn --no-local-database gather --text "doi:10.1234/example" --format json

# Resolve supported metadata and create or enrich candidates
acorn gather report.docx --resolve --format yaml
acorn gather report.docx --raw --resolve

Candidates are internal evolving records. Database-backed candidate export and completeness scoring are not currently available.

DOE CODE searches

Use --osti to search DOE CODE for projects or to aggregate credited people and organizations from matching projects.

acorn gather --osti projects "ACORN"
acorn gather --osti people https://orcid.org/0000-0002-2057-9115
acorn gather --osti projects --organization ORNL --organization-role site-owner
acorn gather --osti organizations ORNL --all --format json
acorn gather --osti projects --lab ORNL --all

--lab restricts results to projects submitted by one of DOE’s 17 national laboratories. Laboratory acronyms are case-insensitive. It sets the organization role to site-owner and cannot be combined with --organization or --organization-role. Each persisted project candidate is enriched with the laboratory’s canonical ROR from ACORN’s partner and sponsor vocabularies.

DOE CODE searches return one page by default. --limit controls the upstream page size, --offset selects a later page, and --all retrieves every page sequentially. DOI and ORCID resolver URLs are normalized to the bare identifier expected by DOE CODE. --organization-role can restrict organization matching to site-owner, research, sponsor, contributor, or developer; the default matches any credited role.

Project matches create or enrich candidates using the DOE CODE project ID and DOI when available. Gather retains the project title and description, repository and related websites, sponsoring organizations, and research, contributing, and developing partner organizations. When the repository overtly uses github.com, gather queries the GitHub API for programming languages. A repository on the configured GitLab domain receives equivalent enrichment when GitLab credentials are available. Language names are recorded in meta.technology.

With --resolve, people searches enrich valid ORCID matches with the preferred name, public email, and institution data returned by the ORCID API; project repository links are checked and enriched with provider-reported languages when available. Canonical and additional provider links are also checked for liveness during this optional online stage. A failed lookup retains the original provider data. People and organization searches are report-only. Global --no-local-database keeps all DOE CODE results report-only.

OSTI mode treats positional inputs and --text values as direct queries rather than files or URLs. It requires network access and is incompatible with file filtering, merge-request gathering, and schema analysis options. With --resolve, project DOIs and person ORCIDs use the same raw rendering and structured resolution metadata as local discoveries.

Next stop: Validate a gathered candidate with Check.