Upgrading your ReadMe CLI to rdme@10
Overview
This guide explains how to install rdme@10
for use with ReadMe Refactored. In general, we recommend bi-directional syncing for tasks like:
- Syncing Markdown files
- Syncing API definitions (and editing them visually with the API designer)
- Managing project hierarchy (e.g., versions and categories)
However rdme@10
is useful for more targeted workflows—particularly when syncing happens outside of Git, such as:
- A one-directional sync of an API definition (e.g., if it is generated via a build process and/or is not tracked via your bidirectionally synced Git repo)
- A one-directional sync of Markdown files (e.g., if they are updated via a build process and/or are not tracked via your bidirectionally synced Git repo)
- Any non-syncing processing for an API definition (e.g., validating it, reducing it a set of fewer operations)
rdme@10
only works with ReadMe projects that are using ReadMe Refactored. If you are not yet using ReadMe Refactored, you'll want to userdme@9
.
Upgrading to v10
v10
Step 1(a): Upgrade your CLI version
If you're using the rdme
CLI and it is installed globally via npm
, update it by running the following command:
npm install -g rdme@10
More installation options can be found in our docs.
Step 1(b): Update GitHub Actions Workflow version
If you're using the rdme
GitHub Action, update your GitHub Actions workflow file so your rdme
usage uses the v10
reference like so:
- uses: readmeio/rdme@v10
with:
rdme: openapi validate petstore.json
Step 2: Address v10
Breaking Changes
v10
Breaking Changes-
Enable Bi-Directional Syncing (recommended)
We recommend setting up bi-directional syncing for managing your Markdown files, API definitions and project hierarchy.
- Command Replacements
- Replace:
changelogs
→changelog upload
(see more in step 3 below) - Replace:
custompages
→custompages upload
(see more in step 3 below) - Replace:
docs
(and itsguides
alias) →docs upload
(see more in step 3 below)- Note: if you previously used this command to upload Markdown to the API reference section, you should use
rdme reference upload
instead. See more in step 3 below.
- Note: if you previously used this command to upload Markdown to the API reference section, you should use
- Replace:
openapi
→openapi upload
(see more in step 4 below) - Replace:
categories
→ use Git-based workflow - Replace:
versions
→ use Git-based workflow - Remove:
open
- Replace:
-
Updates to Markdown uploading commands
If you previously uploaded Markdown files to your ReadMe project via one of the following commands:
rdme docs
,rdme changelogs
rdme custompages
(note: this command also supports the uploading of HTML files)
The commands have been updated to the following:
rdme docs upload
(orrdme reference upload
if you're uploading Markdown to your API Reference section)rdme changelog upload
rdme custompages upload
(note: this new command still supports the uploading of HTML files)
The command semantics are largely the same, but with a few small changes:
-
The
--dryRun
flag has been deprecated in favor of--dry-run
. -
The new git-backed ReadMe backend has a clearer separation between the Guides and API reference sections. This means that:
- Markdown pages that live in the Guides section should be synced with
rdme docs upload
- Conversely, Markdown pages that live in the API reference should be synced with
rdme reference upload
.
- Markdown pages that live in the Guides section should be synced with
-
There is no prompt to select your ReadMe project version if you omit the
--version
flag. It now defaults tostable
(i.e., your main ReadMe project version). This flag has also been renamed to--branch
. -
These commands will now automatically validate your frontmatter and flag any issues prior to syncing. This is particularly helpful if you're coming from
rdme@9
or earlier, since the shape of certain frontmatter attributes (e.g.,category
,parent
,hidden
) have slightly changed. If you run this command in a non-CI environment, any outdated frontmatter will be detected and you'll have the ability to migrate it to the new format automatically.
Read more in the respective command docs (
rdme docs upload
,rdme reference upload
,rdme changelog upload
,rdme custompages upload
) and in the ReadMe API migration guide.
-
openapi
has been replaced byopenapi upload
If you previously uploaded API definitions to ReadMe via
rdme openapi
, the command is nowrdme openapi upload
. There are now two main updates:-
Like the Markdown uploading commands above, there is no prompt to select your ReadMe project version if you omit the
--version
flag. It now defaults tostable
(i.e., your main ReadMe project version). This flag has also been renamed to--branch
. -
The flag paradigms have been simplified based on community feedback. With the previous command, the
--id
flag was a hexadecimal object ID (e.g.,687855c3600c6e14c79a94cb
). These IDs lacked readability and required an initial upload to ReadMe to obtain, which made it difficult to upsert API definitions and manage many at scale. Withopenapi upload
and ReadMe Refactored, the--id
flag has been removed in favor of--slug
. Slugs are now the unique identifier for an API definition resource in ReadMe.Unlike the object ID paradigm that was previously used with
--id
, the--slug
flag enables you to define a slug during initial upload. While we encourage you to use this flag and especially encourage slugs that are human-readable and descriptive,--slug
is technically optional. When omitted, your API definition's slug is inferred from the file path or URL to your API definition.If you've migrated your project from our legacy platform and you'd like to continue syncing any previously uploaded API definitions via
rdme
, we recommend either 1) looking at the post-migration file name in ReadMe and using the--slug
flag to refer to that (recommended!) or 2) passing the legacy object ID reference via the--legacy-id
flag (this is a hidden flag and should not be used in new workflows).
Read more in the
rdme openapi upload
command docs and in the ReadMe API migration guide. -
Updated 3 days ago