> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factrove.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Describe what the running code does. Do not invent hosted pricing, launch dates, or security guarantees. Share and viewer links are a configured base URL plus an artifact path. Show localhost and a placeholder origin such as https://library.example.com.

# CLI overview

> Install and configure the Factrove CLI, then read the exact help pages generated from the command spec.

The CLI is a standalone NestJS process that calls the HTTP API. It has no listener of its own. The published npm package is `factrove`. Node.js must be at least 24.7.0 and below 25.

```bash theme={null}
npm install --global factrove
factrove --help
ftrv --help
```

`ftrv` is the same program. `npx factrove` runs it without a global install. With no profile and no API URL, it calls `https://api.factrove.app`. `--api-url`, `FACTROVE_API_URL`, and `factrove configure` override that origin. [Release the CLI](https://docs.factrove.app/guides/releasing-the-cli.md) is the manual publish. It does not run on push.

From a checkout, contributors use `pnpm factrove`. Install dependencies and build the CLI plus the workspace packages it imports. The launcher refuses to start until `apps/cli/dist/main.js` exists:

```bash theme={null}
pnpm install --frozen-lockfile
pnpm --filter @factrove/cli... build
pnpm factrove --help
```

`pnpm factrove` reads `apps/cli/.env` for unset `FACTROVE_API_URL` and `FACTROVE_PROFILE`. The example points that command at `http://localhost:3001`. `node apps/cli/dist/main.js` and the published commands do not read that file. Set `BETTER_AUTH_SECRET` and start the API before configure against a local server. See [Quickstart](https://docs.factrove.app/quickstart.md) and [Troubleshooting](https://docs.factrove.app/guides/troubleshooting.md).

The program help uses the name `factrove`. The pages that follow reprint `factrove --help` and each `factrove <command> --help` text word for word, then list flags that help text omits.

## Configure once

Create a key in the web app at `/account/api-keys`, or with the [session recipe](https://docs.factrove.app/api-reference/overview.md#create-an-api-key-from-a-session). Then:

```bash theme={null}
factrove configure --api-url http://localhost:3001
```

From the repository root, the same step is `pnpm factrove configure`. `ftrv configure` is the same command as `factrove configure`.

See [configure](https://docs.factrove.app/cli-reference/configure.md). The key is not printed.

## Commands

| Command | What it does |
| - | - |
| [factrove --help](https://docs.factrove.app/cli-reference/help.md) | Top-level help |
| [upload](https://docs.factrove.app/cli-reference/upload.md) | Create an artifact, or replace one with `--artifactId` |
| [list](https://docs.factrove.app/cli-reference/list.md) | List your artifacts, or organization-shared ones with `--view org` |
| [get](https://docs.factrove.app/cli-reference/get.md) | Print stored HTML or converted Markdown |
| [share](https://docs.factrove.app/cli-reference/share.md) | Create, password-protect, or revoke a public link |
| [rename](https://docs.factrove.app/cli-reference/rename.md) | Change the library name |
| [delete](https://docs.factrove.app/cli-reference/delete.md) | Delete an artifact after confirmation, or with `--yes` |
| [configure](https://docs.factrove.app/cli-reference/configure.md) | Save a profile key and API origin |

`cp` is not a Factrove command. Precedence, `--endpoint-url`, `--output json`, and the differences from `aws s3` are in [CLI](https://docs.factrove.app/guides/cli.md).

## Output and errors

* Success exit code is `0`. Any failure is `1`.
* Plain upload prints only the artifact id. A replace prints the same id. Plain get prints content bytes. Plain share prints the public URL and whether it is password protected. Plain list prints one artifact per line. Plain rename prints `Renamed {id}.` Plain delete prints `Deleted {id}.`
* `--json` and `--output json` print one JSON line on success. Errors then use `{"error":{"code":"...","message":"..."}}` on stderr.
* `--quiet` is accepted on upload, get, share, list, rename, and delete. Help does not list it.
* `--profile` is accepted on every command. Help lists it on configure.
* Local codes are `FILE_NOT_FOUND`, `INVALID_INPUT`, and `NETWORK_ERROR`. API codes pass through.

A replace can rarely return `500` after the new object is already committed. GET the artifact before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.