Paradoc CLI Projects

A project is a directory managed by the CLI. It contains a manifest that describes the project, a state directory that tracks installed artifacts, and the artifact files themselves. Initialize one with paradoc init.

Initializing a project

paradoc init

In interactive mode, the CLI first prompts for the target directory, then the project title, description, and visibility (public or private). Use --yes to skip prompts:

paradoc init --yes --name "My Project" --visibility private

See the init command reference for all options.

The project manifest

The paradoc.json file in the project root defines your project:

{
  "$schema": "https://schema.paradoc.dev/manifest.json",
  "name": "@your-org/my-project",
  "title": "My Project",
  "description": "A description of your project",
  "visibility": "private",
  "artifacts": {
    "dir": "artifacts",
    "output": "json"
  },
  "registries": {
    "@acme": "https://registry.acme.com"
  },
  "security": {
    "allowedContentTypes": ["application/vnd.acme.form+json"]
  },
  "cache": {
    "ttl": 3600,
    "directory": ".cache/paradoc"
  }
}

Fields

Field	Type	Required	Description
`$schema`	string	No	JSON schema URL for editor validation
`name`	string	Yes	Project identifier in `@org/name` format
`title`	string	Yes	Human-readable project title
`description`	string	No	Project description
`visibility`	`"public"` \| `"private"`	No	Project visibility (default: `private`)
`artifacts`	object	No	Artifact storage configuration
`registries`	object	No	Registry configuration by namespace
`security`	object	No	Download settings
`cache`	object	No	Cache configuration overrides

Artifacts

Controls where artifacts are stored and in what format.

Field	Default	Description
`artifacts.dir`	`"artifacts"`	Directory for downloaded artifacts (relative to project root)
`artifacts.output`	`"json"`	Default output format (see Output formats)

Registries

Maps namespaces to registry URLs. See Registries for details.

Security

Field	Description
`security.allowedContentTypes`	Content types added to the built-in download defaults. Project values replace global additions but cannot narrow the built-in defaults. Blocked types are never allowed

Cache

Field	Default	Description
`cache.ttl`	`3600`	Time in seconds before cached registry data expires
`cache.directory`	`"~/.paradoc/cache"`	Cache directory. Relative paths resolve from the project root

Directory structure

After initialization and installing an artifact, your project looks like this:

my-project/
├── paradoc.json          # Project manifest
├── .paradoc/                   # CLI state directory
│   └── lock.json
└── artifacts/              # Downloaded artifacts
    └── @acme/
        └── residential-lease.yaml

The `.paradoc/` directory

The .paradoc/ directory stores internal CLI state. Together with paradoc.json, it marks the project root. paradoc init creates it empty. You should not edit its files directly — the CLI manages them.

File	Purpose
`lock.json`	Record of installed artifact editions and versions, source URLs, and integrity checksums

The lock file

.paradoc/lock.json records the version, source URL, and integrity checksum written by paradoc add for each installed artifact. For an artifact that has editions, it also records the key of the installed edition. Each entry is keyed by @namespace/name. The CLI does not use the lock file to restore or pin a later install.

Output formats

The CLI supports four output formats for artifact files. Set the default in artifacts.output in the manifest, or override it for one install with paradoc add --output.

Format	Extension	Description
`json`	`.json`	Standard JSON. Portable and widely supported.
`yaml`	`.yaml`	YAML. Easier to read and edit by hand.
`typed`	`.json` + `.d.ts`	JSON file with a companion TypeScript declaration file for type-safe imports.
`ts`	`.ts`	Standalone TypeScript module with the artifact embedded as `as const`.

The typed and ts formats are generated by paradoc generate or by passing --output typed or --output ts to paradoc add.

Use json or yaml if you don't need TypeScript integration. Use typed if you want type-safe imports without changing your JSON source files. Use ts for a single self-contained module.

Projects
Last updated on