> ## 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.

# Quickstart

> Install the Factrove CLI, or run the repository locally, create an API key, and upload an HTML file.

## Install the CLI

The published npm package is `factrove`. It installs `factrove` and `ftrv`. Both run the same program. Node.js must be at least 24.7 and below 25.

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

`npx factrove --help` runs it without a global install.

With no profile and no API URL, the CLI calls `https://api.factrove.app`. `factrove configure`, `--api-url`, `--endpoint-url`, and `FACTROVE_API_URL` override that origin. A self-hosted API needs the override. [Release the CLI](https://docs.factrove.app/guides/releasing-the-cli.md) is how a maintainer publishes a version. Nothing publishes on push.

The rest of this page runs the local repository. From the repository root, contributors use `pnpm factrove` instead of the global install. `pnpm` prints the script line it runs to stderr.

## Get the source

Clone [magnificode-ltd/factrove](https://github.com/magnificode-ltd/factrove) and change into that directory:

```bash theme={null}
git clone https://github.com/magnificode-ltd/factrove.git
cd factrove
```

You need Node.js 24.x, at least 24.7 and below 25 (`>=24.7.0 <25` in `package.json` engines; 24.16 is pinned), pnpm 11.25, and Docker Compose v2.

* [Node.js downloads](https://nodejs.org/en/download)
* [pnpm installation](https://pnpm.io/installation)
* [Docker Compose](https://docs.docker.com/compose/install/)

[Self-hosting](https://docs.factrove.app/guides/self-hosting.md) is the Docker Compose install. [Troubleshooting](https://docs.factrove.app/guides/troubleshooting.md) covers the failures this loop hits most often.

Install dependencies, then build the CLI and the workspace packages it imports. `pnpm factrove` refuses to start until `apps/cli/dist/main.js` exists:

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

`pnpm dev` builds the CLI again before it starts the servers. A checkout you only use for the CLI still needs the filter build above.

## 1. Configure and start local services

Set `BETTER_AUTH_SECRET` in `apps/api/.env` to at least 32 characters before starting the API. The example value is a local placeholder.

```bash theme={null}
cp apps/api/.env.example apps/api/.env
cp apps/cli/.env.example apps/cli/.env
pnpm infra:up
pnpm db:migrate
pnpm db:seed
pnpm dev
```

`pnpm infra:up` starts PostgreSQL on `127.0.0.1:5432` and Garage (local S3) on `127.0.0.1:3900`. `pnpm dev` starts the API on `http://127.0.0.1:3001` and the web app on `http://127.0.0.1:3000`. Compose does not start either application. `pnpm dev` is the local development server.

## 2. Create an account and an API key

Open `http://localhost:3000/signup`, then create a key at `/account/api-keys`. The secret is shown once. Creating the account sends an invite email. With `EMAIL_TRANSPORT` unset or `log`, the API logs that message and does not send it. A plus-address is a valid invitee. The commands for the log, SMTP, and Brevo transports, with the address as a parameter, are in [Invite email](https://docs.factrove.app/guides/self-hosting.md#invite-email). A copyable sign-in and key-creation request is in [API overview](https://docs.factrove.app/api-reference/overview.md#create-an-api-key-from-a-session).

In a second terminal, from the repository root:

```bash theme={null}
pnpm factrove configure
```

The CLI stores the key in `~/.factrove/credentials` (mode 0600). It does not print the key.

## 3. Upload a file

```bash theme={null}
artifact_id=$(pnpm factrove upload ./fixtures/hello.html)
printf '%s\n' "$artifact_id"
pnpm factrove upload ./fixtures/hello.html --name "X launch calendar"
```

Plain success prints only the artifact id on stdout. pnpm writes the script line it runs to stderr, so the substitution above is the id. Omit `--name` and the library name is the file name without `.html` or `.htm`. A stem that is empty, longer than 120 characters, or not one line stores null, and the upload still succeeds. A later replace keeps that name unless you pass `--name` again. Open it at:

```text theme={null}
http://localhost:3000/artifacts/{id}
```

`--json` prints the `{ artifact }` envelope on one line. Replace that artifact later with the same file:

```bash theme={null}
pnpm factrove upload ./fixtures/hello.html --artifactId "$artifact_id"
```

If a replace returns `500`, GET the artifact before retrying. Prepare the HTML so it can render under the viewer policy. See [Prepare an artifact](https://docs.factrove.app/concepts.md#prepare-an-artifact).

## 4. Open the library

Visit `http://localhost:3000`. Use **My artifacts** or **Organization artifacts**, then Refresh after an upload. An empty **My artifacts** page shows `npm i -g factrove` (or `npx factrove`), `ftrv` as the same command, `factrove configure --api-url` for this app's API origin, and `factrove upload`, plus a prompt you can paste into a coding agent. The commands in this guide still use `pnpm factrove` because they run from the checkout. The [CLI reference](https://docs.factrove.app/cli-reference/overview.md) lists every command. Organization artifacts stay empty until the account has a membership. Signup and seed do not create one. See [Organization membership](https://docs.factrove.app/concepts.md#organization-membership).

The owner of a private artifact can choose **Share with** the organization name in the viewer. After confirmation, members of that organization can open it. The web app cannot make it private again. The owner can also **Rename** or **Delete** an artifact from the library and the viewer. Delete asks for confirmation, then removes the artifact, its stored HTML, and any public link.

## 5. Share a link (optional)

```bash theme={null}
pnpm factrove share "$artifact_id" --json
```

`--json` prints one `{ share }` line. Plain share output also prints a status line after the URL. Add a password with `--password` (a prompt that needs a terminal) or `--password-stdin`. See [Sharing links](https://docs.factrove.app/guides/sharing-links.md).

## Useful follow-ups

```bash theme={null}
pnpm factrove list
pnpm factrove get "$artifact_id" --format markdown > artifact.md
pnpm factrove rename "$artifact_id" --name "X launch calendar"
pnpm factrove upload ./fixtures/hello.html --artifactId "$artifact_id"
pnpm factrove share "$artifact_id" --revoke
pnpm factrove delete "$artifact_id" --yes
```

A copyable agent workflow is in [CLI](https://docs.factrove.app/guides/cli.md#agent-workflow). Help text still uses synopsis placeholders such as `<artifact-id>`. Those are not shell syntax. Executable examples on this site use quoted variables.

`pnpm factrove` reads `apps/cli/.env` only for unset `FACTROVE_API_URL` and `FACTROVE_PROFILE`. The example sets `FACTROVE_API_URL` to `http://localhost:3001` so that command talks to the local API. `node apps/cli/dist/main.js` and the published `factrove` command do not read that file. Their built-in origin is `https://api.factrove.app`. See [CLI](https://docs.factrove.app/guides/cli.md) for flags and precedence.


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