# How do I publish a package to Pkg?

Company: Socra — Multiply Your Judgment
Canonical URL: https://support.socra.com/articles/art_01m46em7930g4y5g08hj98407m-publish-a-package

Publish a prepared local package with `socra pkg publish` or `npm publish` against the Pkg registry. Each published name and version identifies immutable package bytes, so use a new version when those bytes change. A managed Pkg Release builds from a successful Checkpoint and needs the managed execution path to be available.

## Prepare a local package

Install the Socra CLI with the Account and Pkg plugins and sign in to the Account that will own the package. `socra pkg publish` also requires `bun` and `tar` on your command path.

Check that `package.json` contains the intended name and a valid semantic version, such as `1.2.3`. Run your package's tests and build checks. Review the files included in the packed package.

The local publish command packs and uploads the package. It does not run the managed Release's tests and typecheck for you. The CLI refuses a manifest with `private: true`; keep that setting when the package should remain unpublished.

## Publish through the CLI

From the package directory, run:

```sh
socra pkg publish --visibility internal
```

Use `--visibility public` when creating a Package that anyone may install. This option supplies the initial visibility when publication creates the Package. It does not change an existing Package's visibility.

Use `--root PACKAGE_DIRECTORY` to select another directory or `--tag TAG` for a distribution tag other than `latest`. The success response identifies the published name and version.

## Publish through npm

Configure authentication for the intended Account:

```sh
socra pkg configure
export SOCRA_ACCESS_TOKEN="$(socra pkg access-token)"
```

Then run this command from the package directory:

```sh
npm publish --registry=https://pkg.socra.cloud/npm/
```

A new Package created by this upload defaults to `internal`. Keep the token out of the package contents and logs. Refresh the shell's token before a later publication if needed.

## Managed Releases

For a managed Package, replace `PACKAGE` with its name or `pkg_…` ID. Inspect its successful Checkpoints and start a Release from its latest Checkpoint:

```sh
socra pkg checkpoint list PACKAGE
socra pkg release create PACKAGE
```

Use `--checkpoint CHECKPOINT_ID` with a `pchk_…` ID on the create command to select another Checkpoint belonging to the Package. Wait for active Changes or Releases to finish before starting another Release. Pkg assigns the new version and starts the build asynchronously.

Keep the returned `prel_…` ID. Check the Release until its status is `succeeded` or `failed`:

```sh
socra pkg release retrieve PACKAGE RELEASE_ID
```

Replace `RELEASE_ID` with that ID. A queued Release is not a completed publication. Read the error if the Release fails.

If you receive the storage-migration error, new package sandboxes are disabled. An existing Checkpoint does not bypass that restriction. See [Why does my Pkg Change fail during storage migration?](https://support.socra.com/articles/art_01m3zvnd1yzewn3tkw8qz5t3yv-change-storage-migration) for the recovery boundary.

A direct npm upload does not create a managed source workspace. Use a verified local upload when you maintain the source outside Pkg's managed workspace.

## Verify the publication

Replace `PACKAGE` and `VERSION` with the published package name and exact version:

```sh
npm view PACKAGE@VERSION --registry=https://pkg.socra.cloud/npm/
```

Check the name, version, distribution tag, and artifact integrity. Install that exact version in a separate test application and check that it can import the package's public entry point.

If a command stops before returning a result, inspect the registry before repeating it. The upload may already own that version. Pkg rejects an existing name and version instead of overwriting it.

## Article details

- Collection: [Pkg](https://support.socra.com/collections/col_01m3z6vv74g6nshqaz3wpy8704-pkg)
- Canonical: https://support.socra.com/articles/art_01m46em7930g4y5g08hj98407m-publish-a-package