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

# upload

> Upload an HTML file as a new artifact and print its id.

```text theme={null}
Usage: factrove upload <file> [--name <name>] [--artifactId <id>] [--access private|org_shared] [--json]

Uploads an HTML file. Without --artifactId it creates a new artifact and prints
only its id. With --artifactId it replaces that artifact's content and prints the same id.
--name sets the name shown in the library. Omit it and the name is the file name
without .html or .htm. On replace, omit --name to keep the current name.

Options:
  --name <name>                  Name shown in the library. One line, up to 120 characters.
  --artifactId <id>              Replace this artifact instead of creating a new one.
  --access <private|org_shared>  Who can see a new artifact (default: private).
  --json                         Print one JSON line.
```

## Accepted flags

The help text above is exact. These flags are also accepted, including ones that help text does not list.

* `--name <name>` — Name shown in the library. One line, up to 120 characters.
* `--artifactId <id>` — Replace this artifact instead of creating a new one.
* `--access <private|org_shared>` — Who can see a new artifact (default: private).
* `--json` — Print one JSON line (alias: --output json).
* `--output <json|text>` — Print one JSON line when the value is json. --output text is the plain output.
* `--api-url, --endpoint-url <origin>` — API origin (alias: --endpoint-url).
* `--profile <name>` — Credentials profile (default: default). Accepted on every command. Help lists it on configure.
* `--quiet` — Accepted on upload, get, share, list, rename, and delete. It does not hide their output. Help does not list it. configure rejects it.
* `-h, --help` — Show help.

## Behavior

Plain success prints only the new id. `--json` prints one `{ artifact }` line.

`--artifactId` replaces content and prints the same id. The API keeps the current access and any share token. `--access` with `--artifactId` is rejected before a request is sent. Only the owner can replace. Anyone else gets `404 ARTIFACT_NOT_FOUND`.

The file must be non-empty UTF-8 `.html` or `.htm` and at most 10,485,760 bytes. `--access org_shared` requires a current organization membership. Signup does not create one. See [Concepts](https://docs.factrove.app/concepts.md#organization-membership).

Another replace of the same revision returns `409 CONTENT_CONFLICT`. A replace can return `500` after the new object is already committed. GET the artifact before retrying. Replacement does not keep version history and normally deletes the previous object.

## Related

* [CLI](https://docs.factrove.app/guides/cli.md)
* [Upload an HTML file](https://docs.factrove.app/api-reference/artifacts/upload-an-html-file.md)
* [Replace an artifact's stored HTML](https://docs.factrove.app/api-reference/artifacts/replace-an-artifacts-stored-html.md)


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