{
  "__type": "IngestedDoc",
  "__tag": 4010,
  "_content": {
    "Notes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Raises": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Yields": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Methods": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Returns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Send each "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": ".papyri"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " artifact (or pack a DocBundle directory on the fly) to the viewer ingest endpoint."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Receives": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warnings": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Attributes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Extended Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Accepted input forms:"
            }
          ]
        },
        {
          "__type": "BulletList",
          "__tag": 4053,
          "ordered": false,
          "start": 1,
          "children": [
            {
              "__type": "ListItem",
              "__tag": 4054,
              "children": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": ".papyri"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " file: loaded directly."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "ListItem",
              "__tag": 4054,
              "children": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": ".zip"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " file: must contain exactly one "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": ".papyri"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " member; that   member is extracted and uploaded.  The zip is validated before the   network request is made."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "ListItem",
              "__tag": 4054,
              "children": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "DocBundle directory: passed through "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "papyri.pack.make_artifact_from_dir"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "   so the bytes on the wire are identical to what "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "papyri pack"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " would   produce — same validation, same byte-reproducibility guarantees."
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The viewer's "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "/api/bundle"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " endpoint runs the full ingest pipeline server-side; this is the canonical way to ship a bundle into the cross-linked graph."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Strong",
              "__tag": 4048,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "Named targets"
                }
              ]
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " (recommended for repeated use)      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "# ~/.papyri/config.toml\n[upload.targets.staging]\nurl = \"https://staging.example.com/api/bundle\"\ntoken = \"my-token\"\n\n[upload.targets.production]\nurl = \"https://docs.example.com/api/bundle\"\nkeychain = true   # token stored in system keychain",
          "execution_status": null
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Then: "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "papyri upload --to staging mybundle.papyri"
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "For keychain targets, store the token once with      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "python -m keyring set papyri production",
          "execution_status": null
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Strong",
              "__tag": 4048,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "Token resolution order"
                }
              ]
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ": "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "--token"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " flag > "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "--to"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " target (config file or keychain) > "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "$PAPYRI_UPLOAD_TOKEN"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " env var."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Strong",
              "__tag": 4048,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "URL resolution order"
                }
              ]
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ": "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "--url"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " flag > "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "--to"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " target > "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "$PAPYRI_UPLOAD_URL"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " env var > "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "http://localhost:4321/api/bundle"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Deduplication: before each upload the SHA-256 of the artifact is checked against the viewer (a "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "GET"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " to the same endpoint).  When the server already holds an identical bundle for that "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "(module, version)"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " the upload is skipped.  Pass "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "--force"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " to upload regardless."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Other Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    }
  },
  "_ordered_sections": [
    "Summary",
    "Extended Summary",
    "Parameters",
    "Attributes",
    "Methods",
    "Returns",
    "Yields",
    "Receives",
    "Other Parameters",
    "Raises",
    "Warns",
    "Warnings",
    "Notes"
  ],
  "item_file": "/papyri/cli/upload.py",
  "item_line": 152,
  "item_type": "function",
  "aliases": [
    "papyri._cmd"
  ],
  "example_section_data": {
    "__type": "Section",
    "__tag": 4015,
    "children": [],
    "title": [],
    "level": 0,
    "target": null
  },
  "see_also": [],
  "signature": {
    "__type": "SignatureNode",
    "__tag": 4029,
    "kind": "function",
    "parameters": [
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "paths",
        "annotation": "Annotated[list[Path], typer.Argument(help='Paths to upload. Each path is a ``.papyri`` artifact (produced by ``papyri pack``), a ``.zip`` file containing exactly one ``.papyri`` artifact, or a DocBundle directory (packed on the fly, output unchanged from ``papyri gen``).')]",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": {
          "__type": "Empty",
          "__tag": 4031
        }
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "to",
        "annotation": "Annotated[str | None, typer.Option('--to', help=\"Named upload target defined in ~/.papyri/config.toml (e.g. 'staging', 'production').  Overrides $PAPYRI_UPLOAD_URL / $PAPYRI_UPLOAD_TOKEN.  Explicit --url / --token flags override --to.\")]",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "None"
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "url",
        "annotation": "Annotated[str | None, typer.Option('--url', '-u', help='URL of the viewer ingest endpoint.  Overrides --to and $PAPYRI_UPLOAD_URL.  Defaults to $PAPYRI_UPLOAD_URL, then the target set by --to, then http://localhost:4321/api/bundle.')]",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "None"
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "token",
        "annotation": "Annotated[str | None, typer.Option('--token', '-t', help='Bearer token for /api/bundle authentication.  Overrides --to and $PAPYRI_UPLOAD_TOKEN.  Defaults to $PAPYRI_UPLOAD_TOKEN, then the target set by --to.  Omit when the viewer has no token configured (local dev).')]",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "None"
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "verbose",
        "annotation": "Annotated[bool, typer.Option('--verbose', '-v', help='Show per-step packing progress when building a bundle on the fly.')]",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "False"
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "force",
        "annotation": "Annotated[bool, typer.Option('--force', '-f', help='Upload even when the viewer already holds an identical bundle. By default a SHA-256 of the artifact is checked against the server first and matching bundles are skipped.')]",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "False"
      }
    ],
    "return_annotation": "None",
    "target_name": "upload"
  },
  "references": null,
  "qa": "papyri.cli.upload:upload",
  "arbitrary": [],
  "local_refs": []
}