diff --git a/.changeset/move-to-graphql-sdk.md b/.changeset/move-to-graphql-sdk.md deleted file mode 100644 index c5b9160..0000000 --- a/.changeset/move-to-graphql-sdk.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -"@team-plain/cli": major ---- - -Move to `@team-plain/graphql`, the replacement for the deprecated `@team-plain/typescript-sdk`. - -- Requires Node.js 22.12 or later. Node.js 18 and 20 are end of life. To stay on them, pin `@team-plain/cli@0`. -- The API key needs the `knowledgeSource:create` permission. The README and `--help` previously said `indexedDocument:create`, which was wrong. -- Errors now print as a single line with the error code, without a request ID or stack trace. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c834ed..193f665 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # @team-plain/cli +## 1.0.0 + +### Major Changes + +- 1f7051a: Move to `@team-plain/graphql`, the replacement for the deprecated `@team-plain/typescript-sdk`. + + - Requires Node.js 22.12 or later. Node.js 18 and 20 are end of life. To stay on them, pin `@team-plain/cli@0`. + - The API key needs the `knowledgeSource:create` permission. The README and `--help` previously said `indexedDocument:create`, which was wrong. + - Errors print as a single line, with the API error code where there is one, in place of the request ID. + - Passing more arguments than a command takes is now an error. `plain index-url a b` previously indexed `a` and ignored `b`. + ## 0.4.0 ### Minor Changes diff --git a/README.md b/README.md index fb92334..0a476f8 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,41 @@ +
+ Plain +
+ + # @team-plain/cli -This CLI is used to interact with the Plain.com API. +CLI for interacting with the [Plain](https://www.plain.com) API. + +Specifically for indexing content as +[Knowledge Sources](https://www.plain.com/docs/product/agents/knowledge-sources) in your Plain +workspaces, to be used by [Plain Agents](https://www.plain.com/docs/product/agents). + +- [Installation](#installation) +- [Authentication](#authentication) +- [Commands](#commands) + - [Knowledge Sources](#knowledge-sources) + - [`index-url`](#index-url) + - [`index-sitemap`](#index-sitemap) +- [Running in CI](#running-in-ci) -If you run into any issues please open an issue or get in touch with us at [help@plain.com](mailto:help@plain.com). ## Installation Requires Node.js 22.12 or later. -``` +```bash npm install -g @team-plain/cli -``` - -This installs the package globally and makes the `plain` command available in your path. - -The cli has a help command that can be used to get more information about the available commands: - -``` plain --help ``` ## Authentication -To authenticate with your Plain workspace, the CLI uses a [Plain API Key](https://www.plain.com/docs/api-reference/graphql/authentication). The key is read from the environment variable `PLAIN_API_KEY`. +To authenticate with your Plain workspace, the CLI uses a +[Plain API Key](https://www.plain.com/docs/api-reference/graphql/authentication), read from the +`PLAIN_API_KEY` environment variable. -See below for permissions required for each command. - -``` +```bash export PLAIN_API_KEY=plainApiKey_xxx ``` @@ -34,7 +43,14 @@ export PLAIN_API_KEY=plainApiKey_xxx ### Knowledge Sources -These commands add pages to Plain as [knowledge sources](https://www.plain.com/docs/product/agents/knowledge-sources), which Ari uses to answer customers. Plain fetches and indexes the content of each URL. Running a command again for a URL that's already a knowledge source reindexes it. +Commands for indexing content as +[Knowledge Sources](https://www.plain.com/docs/product/agents/knowledge-sources) in your Plain +workspace, so that [Plain Agents](https://www.plain.com/docs/product/agents), such as +[Ari](https://www.plain.com/docs/product/agents/ari), can use it to answer customer questions and as +context. + +Each command fetches and indexes the content of the provided URL or sitemap. Running a command again +for a URL or sitemap that's already a knowledge source reindexes it. ### `index-url` @@ -42,8 +58,8 @@ Index a single page by URL. Required permissions: `knowledgeSource:create` -``` -plain index-url +```bash +PLAIN_API_KEY=plainApiKey_xxx plain index-url ``` Options: @@ -56,17 +72,19 @@ Index all the urls in a given sitemap you provide. Required permissions: `knowledgeSource:create` -``` -plain index-sitemap +```bash +PLAIN_API_KEY=plainApiKey_xxx plain index-sitemap ``` Options: -- `-l, --labelTypeIds `: Array of label type IDs to associate with the indexed urls from the sitemap +- `-l, --labelTypeIds `: Array of label type IDs to associate with the indexed urls + from the sitemap ## Running in CI -Pin the major version so a future breaking release can't change your workflow unannounced. For example, to reindex your docs from GitHub Actions: +Use the CLI in your CI pipeline to index your content as Knowledge Sources, for example when you +publish new documentation to a Mintlify site. ```yaml - uses: actions/setup-node@v7 diff --git a/logo.png b/logo.png new file mode 100644 index 0000000..34a1e81 Binary files /dev/null and b/logo.png differ diff --git a/package.json b/package.json index 710494d..a80b303 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@team-plain/cli", "private": false, - "version": "0.4.0", + "version": "1.0.0", "description": "CLI for interacting with the Plain API", "repository": { "type": "git",