If you maintain a Currículo Lattes, a small correction can become a fragile manual task: export the file, find the right XML element, edit it without breaking the document, and remember what changed before importing it again.

This tutorial shows a safer local workflow with lattes-toolkit. We will use the stable v2.4.0 release to read an exported XML file, change one typed field, preserve a backup, and verify the result before the human-controlled import step.

TL;DR

@paladini/lattes-toolkit is a TypeScript library and CLI for working with XML that you already have. It does not log in to Plataforma Lattes, download a curriculum, or click Import XML for you. That boundary is useful: the file stays local, and the final review remains explicit.

The core workflow is:

  1. Export your XML from Plataforma Lattes.
  2. Parse and inspect it locally.
  3. Apply a narrow change.
  4. Confirm the generated XML and keep the automatic backup.
  5. Review and import the file manually.

The CNPq description of Plataforma Lattes explains the platform's role in Brazilian research information. The toolkit is an independent project and is not affiliated with CNPq.

Prerequisites

You need:

  • Node.js 18 or later.
  • An XML or ZIP export that you are allowed to edit.
  • A terminal and a text editor.
  • A separate copy of the original file before experimenting.

This tutorial is pinned to @paladini/lattes-toolkit@2.4.0, released from the repository's v2.4.0 tag. Pinning the version makes the commands reproducible even if npm's latest dist-tag moves later.

Install the pinned CLI

You can install the package in a project or invoke its CLI with npx:

npm install @paladini/lattes-toolkit@2.4.0 npx @paladini/lattes-toolkit@2.4.0 --help

The package declares Node.js >=18.0.0, uses the MIT license, and exposes the lattes-toolkit command. The help output is the quickest way to check that the expected CLI is available:

Usage: lattes-toolkit init [dir] lattes-toolkit parse <file.xml|zip> [--json|--summary] lattes-toolkit get <file> <path> lattes-toolkit set <file> <path> <value> lattes-toolkit serialize <file.json> -o <out.xml> lattes-toolkit backup list [dir] lattes-toolkit restore [--last|<backup-id>] [dir] lattes-toolkit validate <file.xml> [--dtd [file.dtd]] lattes-toolkit patch <file.xml> <patches.json>

Inspect an exported curriculum

Export your curriculum through the normal Plataforma Lattes interface and save it as curriculo.xml. Do not place a real curriculum in a public repository or issue. It contains personal data.

Start with a summary:

npx lattes-toolkit@2.4.0 parse curriculo.xml

If you need a particular field, use dot and bracket notation. For example, this reads the first journal article title:

npx lattes-toolkit@2.4.0 get curriculo.xml bibliographicProduction.journalArticles[0].title

The field names come from the toolkit's typed model, not from a guess about raw XML capitalization. The repository documents CLI commands and typed field coverage.

Make one narrow edit

Suppose the summary needs a correction. Use set with the exact path and value:

npx lattes-toolkit@2.4.0 set curriculo.xml identification.summary "A corrected professional summary."

The command serializes the XML back to the same path. When that destination already exists, the toolkit creates a snapshot under .lattes-backup/ before overwriting it. The backup documentation describes the manifest, SHA-256 value, retention behavior, and restore commands.

List the available snapshots:

npx lattes-toolkit@2.4.0 backup list

If the result is not what you expected, restore the latest snapshot before trying again:

npx lattes-toolkit@2.4.0 restore --last

For multiple edits, prefer patch with an allowlist rather than giving an automated process unrestricted access to the document:

{ "allowlist": ["identification.summary"], "patches": [ { "path": "identification.summary", "value": "A corrected professional summary." } ] }

Save that as patches.json, then run:

npx lattes-toolkit@2.4.0 patch curriculo.xml patches.json

An allowlist is a practical safety boundary. It makes the intended edit reviewable and prevents a broad instruction from silently changing unrelated sections.

Verify before import

Read the edited field again:

npx lattes-toolkit@2.4.0 get curriculo.xml identification.summary

The package also includes an XSD-based validation command. It uses xmllint when that tool is available in your environment:

npx lattes-toolkit@2.4.0 validate curriculo.xml

Validation is not a promise that the Plataforma Lattes interface will accept every file. The project's documentation explicitly describes XSD and optional local DTD checks as environment-dependent, and says that schema validation does not guarantee platform acceptance.

For a programmatic workflow, the same boundaries are available in TypeScript:

import { readFileSync } from "node:fs"; import { applyCurriculumPatches, readCurriculum, writeCurriculum, } from "@paladini/lattes-toolkit"; const curriculum = await readCurriculum( readFileSync("./curriculo.xml"), ); applyCurriculumPatches( curriculum, [{ path: "identification.summary", value: "A corrected professional summary." }], { allowlist: ["identification.summary"] }, ); await writeCurriculum(curriculum, "./curriculo.xml");

After writing, parse the file again and inspect the changed field. Then open the XML in the Plataforma Lattes interface, review it, and perform the import yourself. The toolkit does not automate login or submission.

Why this workflow is safer

The library models supported fields as typed data, while retaining unmapped document content during the XML round trip. That is more deliberate than using a regular expression over XML text. The set command is useful for one field, while patch makes a batch change auditable through a JSON file.

Automatic snapshots address a different risk: editing the right field but disliking the result. The backup is local and should be excluded from Git with .lattes-backup/ in .gitignore.

The release history also matters. Version 2.0.0 introduced breaking model and serialization changes aligned with the repository's versioned XSD. Version 2.4.0 added typed technical-production fields. Pinning a release avoids accidentally mixing this tutorial with a future CLI or model change.

Failure modes and limits

The field path is wrong

A path that is not present in the typed model will not produce the intended update. Start with parse, consult the field coverage documentation, and make one small change at a time.

xmllint is unavailable

The validation command can report that validation was skipped when the required executable or local DTD is missing. Treat that as a missing verification step, not as proof that the file is valid.

The platform rejects the import

The toolkit cannot guarantee acceptance by Plataforma Lattes. Keep the original export, inspect the backup, and use the platform's own error message and documentation. Do not use the library to bypass a CAPTCHA, terms of use, or a required manual review.

Personal data leaks

Curricula contain personally identifiable information. Work on local copies, do not upload real XML to chat or public issue trackers, and use synthetic or anonymized fixtures for tests. The project explicitly says it does not download a curriculum from the public web or query a CPF.

FAQ

Does this package edit the online curriculum directly?

No. It edits an XML or ZIP file that you already have. Export and import remain manual.

Can I use it with an AI agent?

Yes, but give the agent a narrow allowlist, require a re-parse after writing, and keep the import step under human control. The repository has an AI-agent integration guide.

Does validate prove the import will work?

No. It can check against the packaged XSD when xmllint is available. Platform acceptance has additional behavior outside the toolkit's control.

Is this an official CNPq package?

No. It is an independent MIT-licensed project and states that it is not affiliated with CNPq.

Takeaway

Treat a Currículo Lattes export as a local, reviewable data file: pin the tool version, change only named fields, keep automatic snapshots, validate when possible, and import manually after checking the generated XML. That gives you repeatable edits without pretending that a local parser can replace the platform's own review and submission controls.

Have you found a useful field-level Lattes workflow that benefits from an allowlist and a generated backup?

AI assistance disclosure: I used AI assistance to organize and draft this tutorial. The commands, version details, project behavior, limitations, and links were checked against the paladini/lattes-toolkit v2.4.0 sources and a pinned CLI smoke test before publication.