Frequently Asked Questions (FAQ)

General Questions

What is OneCite?

OneCite is a universal citation and academic reference toolkit that helps you manage bibliographic data. It automates the process of converting various reference formats (DOI, titles, arXiv IDs, etc.) into clean, properly formatted citations in BibTeX, APA, or MLA formats.

How much does OneCite cost?

OneCite is completely free and open-source. It’s licensed under the MIT License.

What do I need to use OneCite?

You need:

  • Python 3.7 or higher

  • pip (Python package manager)

  • An internet connection (for data source access)

That’s it! Just run pip install onecite and you’re ready to go.

Installation Questions

Can I use OneCite on Windows?

Yes! OneCite works on Windows, macOS, and Linux. Simply follow the installation instructions for your system.

I’m getting a permission error when installing. What should I do?

Try one of these solutions:

  1. Use a virtual environment (recommended):

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install onecite

  2. Or use the --user flag:

    pip install --user onecite

Can I install OneCite from source?

Yes! Clone the repository and install in development mode:

git clone https://github.com/HzaCode/OneCite.git
cd OneCite
pip install -e ".[dev]"

Usage Questions

What file formats can I input?

OneCite accepts:

  • Plain text (.txt) - One reference per line or separated by blank lines

  • BibTeX (.bib) - Standard BibTeX format

  • Direct identifiers - DOI, arXiv ID, PMID, ISBN, GitHub URLs, or plain text queries

Can I use OneCite with Overleaf?

Yes! Here’s how:

  1. Generate your bibliography locally:

    onecite process references.txt -o mybib.bib

  2. Upload mybib.bib to your Overleaf project

  3. In your LaTeX file:

    \bibliography{mybib}
\bibliographystyle{plain}

  4. Compile and you’re done!

How do I handle ambiguous references?

Use interactive mode to manually select the correct match:

onecite process references.txt --interactive

When multiple matches are found, you’ll be prompted to select the correct one.

Can I process multiple files at once?

Yes! Use a shell loop:

# On macOS/Linux
for file in *.txt; do
    onecite process "$file" -o "${file%.txt}.bib"
done

# On Windows PowerShell
Get-ChildItem *.txt | ForEach-Object {
    onecite process $_.FullName -o "$($_.BaseName).bib"
}

Data Source Questions

What data sources does OneCite use?

OneCite integrates with:

  • CrossRef (DOI metadata)

  • Semantic Scholar (AI-powered search)

  • OpenAlex (academic graph)

  • PubMed (biomedical literature)

  • DBLP (computer science)

  • arXiv (preprints)

  • DataCite (datasets)

  • Zenodo (open research)

  • Google Books (book metadata)

Which data source is best for my field?

For Biomedical Research: - Use PMID when available - OneCite will prioritize PubMed for medical terms

For Computer Science: - Use arXiv ID for preprints - Use DOI from DBLP when available - OneCite will prioritize CS-related sources

For General Academic Work: - Use DOI (most comprehensive) - Fall back to title + author for identification

Do I need API keys?

No! OneCite works without any API keys or authentication. All data sources are accessed through public APIs.

Output Format Questions

What output formats are supported?

OneCite supports:

  • BibTeX - For LaTeX/Overleaf documents

  • APA - American Psychological Association style

  • MLA - Modern Language Association style

Can I customize the output format?

Yes! OneCite uses YAML-based templates. See Custom Templates for details on creating custom formats.

How do I convert between formats?

Simply re-process your references with a different format:

# Convert to APA
onecite process input.bib --output-format apa -o output_apa.txt

# Convert back to BibTeX
onecite process input.bib --output-format bibtex -o output_new.bib

Can I get the output as plain text instead of a file?

Yes, when using the Python API:

from onecite import process_references

result = process_references(
    input_content="10.1038/nature14539",
    output_format="apa"
)

print(result['output_content'])

Python API Questions

Can I use OneCite in my Python project?

Yes! Import and use it like any Python library:

from onecite import process_references

result = process_references(
    input_content="10.1038/nature14539",
    output_format="bibtex"
)
print(result['output_content'])

See Python API Reference for detailed examples.

How do I handle errors in the API?

from onecite import process_references, ValidationError, ParseError

try:
    result = process_references(
        input_content="invalid_reference",
        output_format="bibtex"
    )
except ValidationError as e:
    print(f"Validation error: {e}")
except ParseError as e:
    print(f"Parse error: {e}")

Can I use callbacks for custom handling?

Yes! Use the interactive_callback parameter:

def my_selector(candidates):
    return 0  # Always select first match

result = process_references(
    input_content="ambiguous reference",
    interactive_callback=my_selector
)

MCP Integration Questions

What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI assistants with tools. It lets Claude and other AI assistants directly use OneCite.

How do I set up MCP integration?

See AI Assistant Integration with MCP for detailed setup instructions for Claude Desktop and Cursor.

Can I use OneCite with other AI assistants?

OneCite is compatible with any AI assistant that supports MCP, including:

  • Claude (Claude Desktop)

  • Cursor Editor

  • Other future MCP-compatible assistants

Troubleshooting Questions

OneCite keeps skipping my references. Why?

Possible reasons:

  1. Empty or malformed references - Check input formatting

  2. Unrecognized format - Try using more specific identifiers (DOI instead of title)

  3. Data source unavailable - Try again later

  4. Too broad reference - Add more details (author, year, etc.)

Solution: Run with verbose output to see warnings:

onecite process references.txt  # Remove --quiet flag

I’m getting “Connection Error”. What does it mean?

This means OneCite couldn’t connect to one or more data sources. Check:

  1. Internet connection - Ensure you’re online

  2. Data source status - Some services may be temporarily down

  3. Firewall/Proxy - Corporate proxies may block external APIs

Try again later or contact support if the issue persists.

Why are my references incomplete?

OneCite retrieves what’s available in the data sources. Some references may have limited metadata. To improve results:

  1. Use more specific identifiers (DOI vs. title)

  2. Add more context (author names, year)

  3. Check if the paper exists in multiple data sources

Can I use OneCite offline?

OneCite requires internet access to query academic databases. However, once you’ve processed references, the output can be used offline.

Performance and Limitations

How many references can I process at once?

OneCite can handle large batches. For optimal performance:

  • Up to 100 references: Use normal mode

  • 100+ references: Use --quiet mode for faster processing

For very large batches (1000+), split into chunks:

split -l 100 large_file.txt chunk_
for chunk in chunk_*; do
    onecite process "$chunk" -o "${chunk}.bib" --quiet
done

How long does processing take?

Typically:

  • Single reference: 1-3 seconds

  • 10 references: 10-30 seconds

  • 100 references: 2-5 minutes

Times vary depending on data source responsiveness and network speed.

Is there a rate limit?

OneCite respects rate limits of data sources. If you hit a rate limit:

  1. The tool will wait and retry

  2. Or skip that reference and continue

  3. You can retry later

Contributing & Support

How can I contribute to OneCite?

See Contributing to OneCite for guidelines on:

  • Reporting bugs

  • Suggesting features

  • Submitting pull requests

  • Improving documentation

Where can I report bugs?

Report issues on GitHub: https://github.com/HzaCode/OneCite/issues

Can I suggest new features?

Yes! Open a feature request on GitHub or discuss in the discussions section.

Where do I get help?

  • Check the documentation: Quick Start Guide

  • Search existing issues on GitHub

  • Ask in GitHub discussions

  • Contact the team for specific problems

Next Steps