After the substantial workflow foundation introduced in v1.2.0, this release takes the next practical step: establishing where workflows belong, clarifying the boundaries between different kinds of workflow repositories, and adding a small set of examples that make the existing workflow system easier to understand.
It is a plumbing and documentation release.
There are no new remote workflow commands in v1.2.1. No catalog browsing, installation, publishing, private repository authentication, or remote execution has been added. Instead, the release prepares the project for those capabilities without prematurely building them.
Examples Are Examples
RESERVE now includes four curated workflow examples under:
Together, these examples demonstrate several parts of the workflow model:
a simple single-series observation;
a transformation pipeline;
multi-series analysis;
runtime parameters and workflow contracts.
They are intentionally readable and modest. Their purpose is to show workflow syntax and CLI capabilities, not to serve as production-grade economic research.
The examples also establish an important rule:
examples/workflows/ is educational source-tree content. It is not the official RESERVE workflow catalog.
That distinction matters as the project grows. Examples may demonstrate simplified data, unusual features, or authoring patterns that do not belong in a curated public collection.
A Clearer Workflow Ecosystem
RESERVE workflows now have clearly defined homes:
examples/workflows/
Educational examples shipped with the source tree.
~/.reserve/workflows/personal/
User-created and locally installed workflows.
reserve-workflows/
The future canonical, curated public workflow collection.
Private repositories/
Future user- or organization-controlled collections.
RESERVE workflow API/
The future distribution boundary between the CLI and repositories.
The official repository is named reserve-workflows.
That name now exists as a first-class internal repository descriptor rather than as a collection of hard-coded GitHub URLs or storage-specific assumptions. The CLI’s future repository operations can depend on the concept of an official repository while remaining independent of how that repository is authored, published, indexed, or stored.
GitHub may be the source of truth for the curated workflow collection. A cloud-based API and supporting distribution services may eventually provide access to that collection. Those implementation details should remain behind the RESERVE workflow API boundary.
The Official Repository Boundary
The internal official repository descriptor identifies:
id: official
name: reserve-workflows
type: official
endpoint: https://api.reservecli.dev/v1
This does not yet enable remote workflow operations. It simply establishes the abstraction that future releases can build upon.
The initial API boundary is intentionally small:
GET /workflows
GET /workflows/{id}
GET /workflows/{id}/{version}
The exact service implementation can evolve later without requiring the CLI to understand GitHub repository layouts, static object paths, R2 buckets, or other infrastructure details.
What Users Will Notice
For most installed users, v1.2.1 is intentionally quiet.
The existing workflow commands continue to work as before:
The new examples are shipped in the RESERVE source repository for developers and contributors. They are not automatically copied into a user’s ~/.reserve/workflows/ directory, and they are not presented as the official catalog.
That keeps the local-first behavior of RESERVE unchanged while giving workflow authors clearer reference material.
Go 1.27.1
RESERVE v1.2.1 also updates the supported release toolchain note to Go 1.27.1.
This is a small implementation detail, but documenting the toolchain used for the release improves reproducibility and gives users and maintainers a clearer baseline for future builds.
A Small Release With a Long-Term Purpose
The goal of v1.2.1 is not to make the workflow system larger. It is to make its boundaries harder to misunderstand.
Examples should remain examples.
Personal workflows should remain local.
The official catalog should have its own repository.
Private repositories should arrive only when their authentication and authorization model is ready.
And the CLI should communicate with repositories through a stable RESERVE abstraction rather than through infrastructure-specific knowledge.
That gives future releases room to add official workflow browsing and installation without turning the local workflow foundation into a tangle of special cases.
RESERVE v1.2.1 establishes the physical and architectural boundaries of that ecosystem, while keeping the user-facing CLI focused, local, and predictable.
One of the recurring goals in RESERVE development has been making sophisticated economic analysis easier to create, understand, and repeat.
As the project has grown, users have increasingly combined data retrieval, transformation, analysis, and visualization commands into pipelines. These pipelines are one of the CLI’s greatest strengths, but they also introduce a practical challenge: a useful analysis often needs to be reconstructed each time it is performed. For agentic users of RESERVE, that translates to avoidable token consumption.
RESERVE 1.2.0 introduces a foundation for solving that problem.
The release adds workflows, a content-first system for creating, documenting, validating, and sharing reusable economic analyses.
A workflow can describe the purpose of an analysis, the economic concepts it covers, the inputs it requires, and the RESERVE pipeline used to perform it. Static workflows can represent fixed analyses with no runtime inputs, while dynamic workflows can accept ordered values such as a start date, end date, country, series, or comparison period.
Version 1.2.0 does not attempt to solve every part of workflow distribution and execution. Instead, it establishes the document format, command model, filesystem layout, validation rules, and safety boundaries upon which the broader workflow ecosystem can be built.
Introducing the Workflow Command
The new workflow command family provides the tools needed to author and inspect reusable analyses:
The command model follows RESERVE’s noun-verb convention. Workflow is the object being managed, while commands such as create, validate, and render describe the action being performed.
The collection README is a normal repository artifact. It can explain the purpose of the collection, document its workflows, and travel with the collection when it is distributed through Git or another repository service. RESERVE scaffolds the initial README but never overwrites existing documentation.
Static and Dynamic Workflows
Not every analysis requires user input.
A static workflow can define a fixed pipeline that is rendered the same way every time. This is useful for established dashboards, recurring reports, classroom demonstrations, or analyses tied to a specific series and period.
Dynamic workflows add an ordered runtime contract.
For example, a GDP summary workflow might declare two inputs:
contract:
- label: start date
format: YYYY-MM-DD
sample: 2020-01-01
description: First date in the analysis period.
- label: end date
format: YYYY-MM-DD
sample: 2024-12-31
description: Final date in the analysis period.
The workflow pipeline refers to these inputs positionally:
pipeline:
- reserve obs get GDP --start @1 --end @2 --format jsonl
- reserve analyze summary
The first supplied value replaces @1, the second replaces @2, and the pattern can continue through @X.
Users and AI agents can inspect the required inputs before rendering the workflow:
reserveworkflowcontractgdp-summary
RESERVE displays the label, expected format, sample value, and description for each input:
personal/economic-growth/gdp-summary contract:
@1 = start date
format: YYYY-MM-DD
sample: 2020-01-01
description: First date in the analysis period.
@2 = end date
format: YYYY-MM-DD
sample: 2024-12-31
description: Final date in the analysis period.
Zero-input workflows are supported as a first-class use case. A workflow only needs a contract when its pipeline contains runtime slots.
Safe Rendering Instead of Execution
An important design decision in RESERVE 1.2.0 is that workflows do not execute pipeline content.
It does not invoke Bash, start another shell, or execute the rendered pipeline.
This boundary is intentional.
Shell execution introduces significant security and cross-platform questions, especially when workflow definitions may eventually come from public, educational, community, or private repositories. Version 1.2.0 keeps the operator or calling agent in control. The rendered command can be reviewed, copied, modified, audited, or executed through an environment chosen by the user.
A future release may introduce explicit rendering targets or controlled execution semantics. Those capabilities may only be added after their portability, trust, and security models are clearly defined.
Validation as a First-Class Feature
Because workflows are intended to become portable artifacts, validation must be more rigorous than simply checking whether a YAML file can be opened.
The new validator checks workflow structure, runtime contracts, pipeline placeholders, and collection-aware references:
Version 1.2.0 also adds several production safeguards:
Unknown YAML fields are rejected instead of being silently ignored.
Multiple YAML documents in one workflow file are rejected.
Runtime slots must match the declared contract.
Repository-style paths cannot traverse outside the configured workflow root.
Symlinks cannot be used to escape the workflow namespace.
A workflow’s reserve_version requirement is checked against the running CLI.
Rendering fails when required runtime values are missing or incompatible.
These rules help authors catch mistakes before publishing a collection and give users greater confidence when inspecting workflows obtained from another source.
A Repository-Aware Foundation
Workflows are organized using a three-part name:
repository/collection/workflow
For example:
personal/economic-growth/gdp-summary
Each part has a distinct purpose.
The repository identifies the source or trust boundary. The collection groups related analyses. The workflow identifies the individual analytical method.
Version 1.2.0 begins with local filesystem storage and uses personal as the default repository for user-authored workflows. The architecture also anticipates additional repository types:
official for workflows maintained and distributed by the RESERVE project
community for collections curated by organizations or subject-matter communities
education for universities, schools, instructors, and home-school networks
private for internal organizational analysis
Remote search, installation, synchronization, signing, and trust policies are not part of this foundational release. However, establishing repository-aware names now means those capabilities can be added later without redesigning the workflow identity model.
A university could eventually distribute a collection through GitHub. A research group could maintain an internal Git repository. A home-school network could publish a shared economics curriculum. RESERVE’s local commands can remain consistent regardless of how those collections are distributed.
Moving Beyond Snippets
Earlier versions included an exploratory feature called snippet.
Snippets helped test the idea that RESERVE pipelines could be saved and reused, but they did not provide the metadata, validation, contracts, collection structure, or repository model needed for a durable ecosystem.
Version 1.2.0 removes the experimental snippet feature and replaces it with workflows.
Because snippets were introduced as a silent exploratory feature and had not been promoted for general use, this was the right point to make a clean transition. Workflows now provide the foundation on which future sharing and distribution capabilities will be built.
Built with Go 1.27
RESERVE 1.2.0 also moves source builds to Go 1.27.
For a data-oriented CLI, the move to Go 1.27 is especially relevant. The release introduces the new encoding/json/v2 implementation, with the established encoding/json API now backed by the newer engine while preserving compatibility. The Go team reports significantly faster JSON unmarshalling, an important improvement for software that regularly processes API responses and JSONL observation streams.
Because RESERVE relies heavily on JSON responses from the FRED® API, we ran our own benchmarks against representative observation data. The results were striking.
Simply compiling RESERVE with the Go 1.27 toolchain produced approximately three times the JSON unmarshalling throughput and reduced unmarshalling time by about 68 percent.
Go 1.27 also introduces size-specialized allocation routines that can reduce the cost of small allocations. In our benchmarks, allocations fell by approximately 80 percent when processing large FRED observation payloads.
These are workload-specific benchmark results rather than a claim that every RESERVE command will run three times faster. They do, however, demonstrate a meaningful improvement in one of the CLI’s most important data-processing paths.
Go 1.27 also strengthens the development toolchain by checking for accidental use of standard-library features newer than the version declared by a module.
Together, these improvements provide a faster and stronger runtime foundation without changing how users interact with RESERVE. Prebuilt binaries remain self-contained, so users installing a RESERVE release do not need to install or upgrade Go separately. Go 1.27 or later is required only when building RESERVE from source, and no workflow or command compatibility changes are required.
RESERVE 1.2.0 is intentionally a foundational release.
It establishes:
A stable workflow YAML format
Static and dynamic workflow contracts
Repository and collection namespaces
Strict validation and version compatibility
Safe, non-executing pipeline rendering
Collection-level documentation
Local creation, discovery, inspection, editing, and removal
A clear path toward future workflow distribution
The next phase will be shaped by real workflow authors and real collections.
That means building analyses, documenting them, testing the contract model, determining which metadata proves useful, and learning how individuals, educators, researchers, and organizations want to distribute their work.
RESERVE began as a tool for retrieving economic data from the command line. It has steadily evolved into a composable environment for transforming, analyzing, and visualizing that data.
With version 1.2.0, those commands can now become durable analytical methods.
Create the workflow once. Validate it. Document it. Render it whenever the question returns.
The original design goals of RESERVE were straightforward: provide intuitive access to the FRED® API while extending that foundation with pipelines, transformations, and analysis capabilities in a single command-line environment.
As the platform has evolved, another design goal has emerged. RESERVE is no longer focused solely on executing commands; it is increasingly focused on helping users capture, repeat, and share economic data workflows.
Economic analysis is rarely a single command invocation. It is often a sequence of retrieval, transformation, filtering, summarization, and visualization steps that users repeat over time.
Version 1.1.7 introduces the first foundation for treating those workflows as reusable assets.
Introducing Snippet Libraries
The headline feature of this release is a new snippet command family:
Snippets provide a mechanism for storing and reusing commonly executed command sequences.
Rather than maintaining shell history entries, personal notes, or external documentation, users can begin building a catalog of repeatable RESERVE workflows directly within the platform.
Importantly, snippets are backed by a filesystem-based library model rather than a temporary or session-oriented implementation.
This establishes a foundation that can scale beyond simple local convenience.
Today’s snippets may be personal workflow shortcuts.
Tomorrow they could become shared libraries, team standards, educational examples, or domain-specific analysis recipes.
Version 1.1.7 is intentionally a soft launch of that capability.
The goal is to establish the foundation before expanding the ecosystem around it.
Reproducibility Matters
Reusable workflows are only valuable if they produce consistent results.
A significant portion of this release focuses on strengthening the reliability of RESERVE’s batch-processing infrastructure through deterministic concurrency testing.
Batch observation and series retrieval now have dedicated testing coverage for:
Concurrency limits
Ordering guarantees
Warning behavior
Fallback paths
Previous test approaches relied on timing assumptions and sleep-based coordination.
The new test framework uses deterministic synchronization mechanisms that make behavior reproducible and easier to validate.
Most users will never see these changes directly.
But they contribute to something important:
Confidence that the same workflow behaves the same way every time it runs.
Preserving Attribution Through Pipelines
Another important improvement in v1.1.7 addresses metadata fidelity.
Recent releases have emphasized citations, provenance, and source attribution as first-class concerns within RESERVE.
This release extends that philosophy into transformation workflows.
Pipeline transformation commands now preserve citation metadata from upstream JSONL inputs, ensuring source attribution remains attached to data as it moves through transformations and resampling operations.
The principle is simple.
Transforming data should not erase information about where that data came from.
As workflows become more sophisticated, preserving provenance becomes increasingly important.
Small Improvements Matter
Not every enhancement in a release needs to be architectural.
Version 1.1.7 also improves ASCII chart rendering by standardizing numeric value labels to fixed two-decimal formatting.
Values such as:
59.00
now align consistently within chart output.
This is a small visual refinement, but one that improves readability when scanning larger datasets.
Polish accumulates over time.
And often the most frequently used features benefit the most from incremental improvements.
Building Beyond Individual Commands
The broader theme of v1.1.7 is not snippets themselves.
It is the idea that economic analysis consists of workflows rather than isolated commands.
Users retrieve data.
Transform it.
Compare it.
Visualize it.
Share the process.
Repeat it.
The new snippet library begins creating a place where those processes can be captured, reused, and eventually shared.
That makes this release more than a quality-of-life improvement.
It represents an early step toward a larger vision for RESERVE: not just a collection of economic data commands, but a platform for building repeatable economic data workflows.
A long string of piped commands can look intimidating at first glance. But they shouldn’t be. In this article, we’ll break down some of the most common RESERVE pipeline commands and show how they work together to build powerful workflows.
The Unix Philosophy
Command-line programs gained popularity in the 1970s with the adoption of an operating system called Unix. After nearly disappearing in the 1990s due to the rise of Microsoft Windows, they regained popularity in the 2000s and have since become mainstream once again. Throughout this evolution, these programs have been designed around a principle known as “The Unix Philosophy”:
Do one thing well and play well with others.
Modern command-line programs like RESERVE actually do many things well, but they are organized into commands and subcommands that keep each task focused and predictable.
RESERVE, for example, includes a series of wrapper commands whose primary goal is to provide direct, consistent access to the FRED API while allowing the user to choose different formats for displaying or storing data. The following command retrieves a range of GDP data and stores it in CSV format for easy import into a spreadsheet:
In addition to RESERVE’s formatting capabilities, this example also demonstrates the left-to-right flow that forms the basis of “play well with others.” In this case, RESERVE hands the data off to the operating system so it can be stored in a file. Just as easily, it could hand the data off to another application.
The Anatomy of a Pipeline
A pipeline takes the output of one command and passes it to another. This sequence flows from left to right.
RESERVE has three major categories of pipeline functionality. The first category consists of wrapper commands that directly access the FRED API and retrieve data. These include commands such as OBS GET and OBS LATEST.
The second category includes true pipeline commands such as TRANSFORM. The idea is simple. A user can retrieve a long range of monthly data and then transform it into quarterly or yearly output.
For example, 20 years of UNRATE data can be resampled from monthly observations into quarterly averages like this:
NOTE: In this example, the TRANSFORM command requires input in JSONL format.
The final category of RESERVE pipeline functionality is ASCII charting through commands such as PLOT and BAR. In the following example, the CHART command receives input from TRANSFORM and generates a visualization directly in the terminal. After all, RESERVE is a command-line interface.
Piped commands in a shell can look complicated at first, but they become much easier to understand when viewed as a logical sequence of steps.
In the examples throughout this post, the workflow was simple:
Get Data -> Transform Data -> Make a Visual
To become comfortable with pipelines, users should focus on understanding each stage independently. Every command should “do one thing well,” while the design of the pipeline handles the “play well with others” part automatically.
In practice, “others” can mean an entire ecosystem of commands and scripts.
Using the CHART example from above, a user can add a standard Unix utility like grep to filter noisy output without changing the original data request. Instead of modifying the OBS GET command or reducing the date range, the pipeline can simply filter the final output:
This is the real strength of pipelines. Each command remains simple, focused, and reusable, but together they can produce powerful workflows with very little effort.
