Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

📥 Download

In a Nutshell

Fetch bucket content or local-model weights with acorn download <SOURCE>.

  • See the configuration documentation for details on configuring ACORN commands.
  • By default, download will save files to ./content in the working directory unless an output path is specified via the --output flag.

Example Usage

# Download research activity data from a single bucket repository URL
acorn download https://code.ornl.gov/research-enablement/buckets/nssd

# Download research activity data from a list of buckets
acorn download --config /path/to/.acorn.json

# Download research activity data to a specific output directory
acorn download --config /path/to/.acorn.yml --output /path/to/output

# Download selected files directly beneath the output directory
acorn download https://github.com/example/project --filter '^examples/quest/' --flatten --output ./quest

# Replace selected paths that already exist in the output directory
acorn download https://github.com/example/project --output ./content --clobber

# Download using JSONC configuration (supports comments and trailing commas)
acorn download --config /path/to/.acorn.jsonc

Buckets

After a bucket transfer, ACORN ingests transferred JSON, JSONC, YAML, YML, and recognized Markdown research activity files into the local research_activities table. Unrelated Markdown documentation is ignored. Each row has a portable NanoID and retains the typed RAD JSON plus provenance for the bucket, repository, relative path, and observation time. Exact DOI, RAiD, ISBN, and patent metadata identities are used when present; a repository-qualified RAD identifier always identifies the transferred activity.

Repeated transfers are idempotent. A matching candidate gains missing fields and unique array values, while conflicting populated fields remain unchanged and are recorded as provenance. Filters and ignore rules apply before transfer, so only transferred RAD files are ingested.

Use --flatten to discard repository directory components and save every selected file as a direct child of the output directory. Filters and ignore rules continue to match the original repository-relative paths. If multiple selected paths have the same filename, the command fails.

By default, a bucket transfer also fails rather than overwrite an existing destination. Add --clobber to replace files, symlinks, or directories that conflict with selected output paths. ACORN obtains the replacement content before removing an existing destination, preserves unrelated contents beneath the output directory, and does not clear the output directory itself. This flag applies only to bucket downloads; the model subcommand’s existing --force flag retains its synchronization-specific meaning.

If a transferred RAD file cannot be parsed or persisted, the files already written to the output directory are preserved and the command fails. Global --no-local-database performs the transfer but skips RAD parsing and candidate persistence.

# Transfer bucket files without creating or updating local candidates
acorn --no-local-database download --config /path/to/.acorn.json

Local vs Remote

The download command copies files from a local ACORN bucket when local file:// URIs are used for associated buckets in the configuration file. Use "git" as the provider for local buckets.

"buckets": [
    {
        "name": "test (local)",
        "repository": {
            "provider": "git",
            "location": "file:./tests/fixtures/data/bucket/"
        }
    },
    {
        "name": "nssd (remote)",
        "repository": {
            "provider": "gitlab",
            "location": {
                "scheme": "https",
                "uri": "https://code.ornl.gov/research-enablement/buckets/nssd"
            }
        }
    }
]

GitLab vs GitHub

The download command supports both GitLab and GitHub remote repositories for ACORN buckets. The configuration for each is similar, with the main difference being the provider field in the repository object.

"buckets": [
    {
        "name": "ccsd (gitlab)",
        "repository": {
            "provider": "gitlab",
            "id": 17410,
            "uri": "https://code.ornl.gov/research-enablement/buckets/ccsd"
        }
    },
    {
        "name": "test (github)",
        "repository": {
            "provider": "github",
            "uri": "https://github.com/jhwohlgemuth/bucket"
        }
    }
]

Models

Download model weights for use with ACORN research harnesses and local inference. By default, ACORN selects GGUF model files from Hugging Face repositories and prefers the Q4_K_M quantization. Python, pip, or the hf tool are not required.

For complete metadata-import options, configuration examples, authentication, and database behavior, see Import model.

# Import GGUF file metadata without downloading weights
acorn import model openai/gpt-oss-20b --search-limit 20

# Import metadata for repositories listed in a local or remote document
acorn import model --model-file https://example.org/models.json

# Download models listed in a local or remote document
acorn download model --model-file https://example.org/models.json

# Select an exact quantization that fits in available GPU memory
acorn download model openai/gpt-oss-20b --quantization Q4_K_M --gpu-memory 24GB

# Download default GGUF (Q4_K_M) from a Hugging Face repo
acorn download model meta-llama/Llama-3.1-8B

# Download model weights into a specific local directory
acorn download model meta-llama/Llama-3.1-8B --local-dir ./models

# Download a specific quantization
acorn download model meta-llama/Llama-3.1-8B --quantization Q8_0

# Exclude low-quality quantizations
acorn download model meta-llama/Llama-3.1-8B --ignore "Q2_|Q3_|imatrix"

# Download models from a config file
acorn download model --config .acorn.json

Use --model-file to load model IDs from a local path, file:// URI, or HTTP(S) URL. Plain-text lists and JSON/YAML lists of IDs or model details are accepted. Positional models, entries from --model-file, and supported --config entries are combined and deduplicated before download. Remote model-list documents cannot be loaded with --offline.

Pass --sync to add the unique model identifiers resolved by this invocation to the ACORN configuration’s models list and to both OpenCode and llama-swap configuration. Existing ACORN model entries are preserved and duplicate identifiers are omitted. Use --sync opencode or --sync llama-swap to select one inference target:

acorn download model openai/gpt-oss-20b --sync
acorn download model openai/gpt-oss-20b --sync opencode
acorn download model openai/gpt-oss-20b --sync llama-swap

--dry-run continues to avoid model downloads and prints ACORN and target-configuration diffs without writing them when combined with --sync. Only models already available in the selected output/models directory can appear in the inference-configuration diffs by default. Add --force to skip this existence check and assume each model is located at <models-dir>/<model-id>:

acorn download model openai/gpt-oss-20b --sync --dry-run --force

Inline --sync is additive and operates only on models resolved by the current download. The standalone acorn sync command remains the full reconciliation operation for every model in ACORN configuration, including target-path and models-directory overrides, independent dry runs, and removal of stale ACORN-managed entries with --prune.

Metadata import resolves the configured revision, records each GGUF file URL, quantization, and byte size, and inspects a selected fallback GGUF repository when the base repository is unavailable or has no GGUF files. It does not transfer model weights or checksum sidecars. --quantization is an ordered, comma-separated exact allowlist. When only --gpu-memory is supplied, ACORN evaluates Q4_K_M. Split shards are treated as one variant and their sizes are summed.

Detailed configuration entries can set the same constraints:

{
    "models": [{
        "name": "gpt-oss",
        "source": {
            "provider": "huggingface",
            "location": "https://huggingface.co/openai/gpt-oss-20b"
        },
        "quantization": ["Q5_K_M", "Q4_K_M"],
        "gpuMemory": "24GB"
    }]
}

Command-line constraints override configuration. If neither constraint is present, download selection remains unchanged. With global --no-local-database, import reports metadata without persisting it and constrained downloads proceed with an eligibility-unknown warning.

Filter and Ignore Semantics

The --filter flag behaves as an include rule: only sources matching at least one pattern will be downloaded. The --ignore flag behaves as an exclude rule: sources matching any ignore pattern are excluded even if they match a filter pattern. Both flags accept regular expression patterns, not Hugging Face glob patterns. Simple patterns are automatically optimized to glob matching for Hugging Face repositories.

Note for Transformers/PyTorch Users

Users of Transformers or PyTorch typically need the full repository or a broader filter that includes config.json, tokenizer files, tokenizer_config.json, and optionally custom code files. The default GGUF-only filter is designed for llama.cpp inference.

Whitelists

A model whitelist restricts downloads to matching user-facing model names. ACORN uses the first non-empty whitelist source in this order: --whitelist or --whitelist-file, application configuration, then ACORN_MODEL_WHITELIST. The environment variable accepts comma-separated inline entries or one remote HTTP or HTTPS whitelist URI. An empty whitelist does not restrict downloads.

Use --whitelist-file to load a whitelist from a remote HTTP or HTTPS URI. For example, the following command allows the requested model only when it appears in the ORNL Research model catalog:

acorn download model openai/gpt-oss-20b --whitelist-file https://research.ornl.gov/api/models.json

The --whitelist option accepts inline model names; it does not fetch a URI supplied as its value.

Configure an inline whitelist with whitelist.models:

{
    "models": [
        "openai/gpt-oss-20b",
        "meta-llama/Llama-3.1-8B",
        "https://huggingface.co/Qwen/Qwen3-8B"
    ],
    "whitelist": {
        "models": [
            "openai/gpt-oss-20b",
            "https://huggingface.co/Qwen/Qwen3-8B"
        ]
    }
}

The models value in the whitelist object accepts either one string or an array of strings:

  • One HTTP or HTTPS URL is treated as a remote whitelist document and fetched when the command runs.
  • An array is treated as inline whitelist entries. Each string may be a model name, model ID, or model URL. URLs inside an array are entries and are not fetched as nested whitelist documents.
  • One non-URL string is treated as one inline whitelist entry.

For example, this configuration loads the whitelist from a remote document:

{
    "models": [
        "openai/gpt-oss-20b",
        "meta-llama/Llama-3.1-8B"
    ],
    "whitelist": {
        "models": "https://example.org/acorn/models.json"
    }
}

The remote document may contain one model-details JSON object with a name or id:

{
    "name": "openai/gpt-oss-20b"
}

It may instead contain a JSON array of model names, IDs, or URLs:

[
    "openai/gpt-oss-20b",
    "meta-llama/Llama-3.1-8B",
    "https://huggingface.co/Qwen/Qwen3-8B"
]

An array of model-details objects is also accepted:

[
    {
        "name": "gpt-oss",
        "id": "openai/gpt-oss-20b"
    },
    {
        "id": "meta-llama/Llama-3.1-8B"
    }
]

For model-details objects, ACORN accepts both name and id as whitelist entries when both are present. At least one of these fields is required. YAML arrays and newline-separated plain-text entries are also supported.

Remote whitelist documents cannot be loaded with --offline. Use --whitelist-file <URI_OR_PATH> when the whitelist document is a local path or file:// URI. An explicitly supplied configuration path must exist; otherwise, ACORN reports Configuration file does not exist.

Next stop: Follow downloaded weights through the model workflow.