Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ara-home/ara/llms.txt
Use this file to discover all available pages before exploring further.
ara add installs one or more packages directly by specifier and saves them to your package.json. It resolves the spec, checks the content-addressed cache, downloads the tarball if needed, scans the package for security issues, extracts it to node_modules/, and updates both package.json and ara.lock — all in a single command. Multiple packages can be added in one invocation.
ara install <spec> is a direct alias for ara add <spec>. Both commands are identical in behavior.Usage
Supported spec formats
| Format | Example | Resolves to |
|---|---|---|
name | react | Latest version from the npm registry |
name@version | react@18.2.0 | Exact version from the npm registry |
name@^range | zod@^3.23.0 | Registry version matching the semver range |
@scope/name | @angular/core | Scoped package from the npm registry (latest) |
@scope/name@version | @angular/core@17.0.0 | Scoped package at an exact version |
user/repo | facebook/react | GitHub repository at the default branch |
user/repo#ref | facebook/react#v18.0.0 | GitHub repository at a specific tag or branch |
| Git URL | https://github.com/user/repo.git | Git repository at HEAD |
| Git URL + ref | https://github.com/user/repo.git#v1.0 | Git repository at a specific tag or commit |
| Tarball URL | https://example.com/pkg.tgz | Direct tarball download |
| Local tarball | ./downloads/pkg.tar.gz | Local .tar.gz or .tgz file |
Flags
Save the package(s) under
devDependencies in package.json instead of dependencies.Save the package(s) under
peerDependencies in package.json.Save the package(s) under
optionalDependencies in package.json.Controls the version range prefix written to
package.json. Accepted values:exact(default) — records the resolved version as-is, e.g.1.2.3caret— prefixes with^, e.g.^1.2.3patch— prefixes with~, e.g.~1.2.3
Re-download the package even if a cached copy exists in the content-addressed store. Use this if you suspect the tarball is stale or corrupted.
Bypass the cache for mutable references such as branch names and floating tags. Guarantees you get the latest commit on a branch even when a cached version exists.
Fail immediately if the requested package is not already present in the local cache. No network requests are made in offline mode.
Suppress interactive security prompts. Packages with findings are auto-approved and a warning is printed instead of asking for your decision.
Generate a
package-lock.json (lockfile version 3) in addition to ara.lock. Temporary compatibility flag for deploy platforms that do not yet support ara.lock.Examples
How add works
For each spec provided,ara add runs the following steps:
- Parse — determines the target type (npm, GitHub, git, tarball URL, or local path).
- Resolve — queries the registry for the latest or best-matching version, or uses the provided ref directly for git and GitHub targets.
- Cache check — skips the network download if the package is already in the content-addressed store (unless
--forceor--refreshis passed). - Fetch — downloads the tarball from the appropriate backend.
- Analyze — scans the package’s source files for 16+ security patterns.
- Prompt — if suspicious patterns are detected and
--non-interactiveis not set, you are asked to allow or deny the package. - Extract — approved packages are written to
node_modules/and stored in the content-addressed store. - Update —
package.jsonis updated with the new dependency entry. - Lock —
ara.lockis rewritten with the full resolved graph.
Security prompt
When a package has findings above themedium risk level, Ara pauses and asks for your decision:
--non-interactive in CI to suppress this prompt and auto-approve all findings.