@aiwg/cli

Paid web resources support passwordless login through aiwg auth login (or --device for headless use), aiwg auth status, and aiwg auth logout. Tokens are held in the native operating-system credential store. The mode-0600 file fallback is disabled unless explicitly selected and allowed.

The agent-optimized execution layer for AIWG

AIWG skills and agents use this CLI to perform common operations with predictable, structured calls instead of spending context on shell discovery, filesystem traversal, command reconstruction, and repeated tool output.

New to AIWG? Install the full aiwg package and let the agentic installer connect the complete system. @aiwg/cli is the smaller execution layer for agents, CI, and web-backed installations.

Install or repair AIWG for this project by following
https://aiwg.io/setup.aiwg.yaml
Explain the plan before changing anything, preserve my existing work, and ask
me only for choices you cannot safely determine.

The equivalent manual path is three steps:

npm install --global aiwg
cd /path/to/your/project
aiwg use all --provider <provider>

The final command deploys, refreshes indices and project context, verifies the provider wiring, and reports one result. Standalone index, regenerate, status, and doctor commands remain advanced maintenance and recovery tools.

Quick Start · Agentic Model · Token Economy · How It Works · Security · Troubleshooting

What This Package Is

@aiwg/cli is the small executable runtime beneath AIWG's skills, agents, rules, and workflows. It is primarily an agent tool, even though an operator can run it from a terminal.

The important product surface is not a long list of commands. The important surface is the AIWG capability graph:

• skills carry task-specific instructions, gates, preservation logic, and recovery guidance;
• agents supply roles, judgment, and orchestration;
• rules supply policy that remains in force across tasks;
• the CLI supplies deterministic lookup, validation, deployment, health, indexing, configuration, and execution primitives;
• signed web releases let the runtime reach the capability graph without bundling the complete corpus into this npm package.

An agent should normally enter through a skill or an AIWG agent and let that resource call aiwg when an imperative operation is needed. This keeps the reasoning layer focused on the user's objective while the CLI handles the mechanical work.

The package includes the aiwg executable, its routing and validation runtime, the Fortemi Core query client, signed web-release verification, verified caching, and provider metadata needed by agentic integrations. It intentionally does not carry the complete agentic/code source tree, project artifacts, or Cockpit.

In practice, this means an agent can:

1. identify the narrow AIWG capability that matches the request;
2. retrieve only that skill or agent definition;
3. follow its gates and call the CLI steps it specifies;
4. consume stable structured output instead of parsing exploratory shell transcripts;
5. leave the project with fewer temporary files, copied resources, and provider-specific assumptions.

Signed resources are available from releases.aiwg.io. A clean installation can use the published capability graph without first copying the full framework corpus into every project.

The Agentic Use Model

AIWG follows a skills-first hierarchy:

user intent
    |
    v
AIWG skill or agent
    |  task knowledge, policy, gates, recovery
    v
small CLI operation
    |  deterministic lookup, validation, mutation, or status
    v
structured result
    |
    v
agent judgment and user-facing outcome

The preferred routing order is:

1. Use an already available AIWG skill or agent. This is the cheapest and best-primed route. The resource already knows the relevant workflow and calls the CLI only where needed.
2. Discover the right AIWG capability. If the resource is not already in context, the agent performs an indexed lookup and retrieves the single best match. It does not recursively browse provider directories or read the whole corpus.
3. Use a raw CLI command only for a basic operator operation, for discovery and status, or as a step inside a skill. Raw action commands lack the task-specific priming carried by skills.

This distinction matters. Running an action command directly may perform the mechanical operation, but the paired skill also explains preconditions, preservation requirements, review gates, failure recovery, and what evidence must be retained. The skill is the workflow; the CLI is its execution substrate.

Examples of the intended pairing:

| Intent | Preferred agentic entry | CLI role | |---|---|---| | Deploy an AIWG framework | use skill | Calls aiwg use with validated provider and project context | | Diagnose an installation | aiwg-doctor skill | Calls aiwg doctor, interprets failures, and guides remediation | | Refresh an installation | aiwg-refresh skill | Previews and invokes refresh safely | | Regenerate provider context | aiwg-regenerate skill family | Preserves operator content while invoking regeneration | | Find a specialized workflow | AIWG capability discovery | Queries the precomputed index and retrieves one matching resource | | Run an executable skill | The selected skill | Dispatches its declared script through the runtime registry |

Operators can still use aiwg use and aiwg doctor directly for basic setup and diagnostics. Agentic systems should prefer the paired skills because they carry the context that a bare command cannot.

Why This Reduces Agent Token Use

General-purpose shell access is flexible, but flexibility is expensive for an agent. Without a purpose-built interface, a session often has to:

• determine where a package was installed;
• enumerate directories and guess which provider copy is authoritative;
• search hundreds or thousands of files;
• read several near-matching documents before finding the right one;
• reconstruct command syntax from help text;
• parse prose-oriented terminal output;
• rediscover safety checks and recovery steps;
• repeat the same investigation in every project or new session.

Each step adds tool calls and returns text that competes with the actual task for context. Recursive listings and broad text searches are especially costly: they describe the storage layout instead of answering the user's intent.

AIWG changes that interaction:

traditional shell-oriented path

locate install
  -> list directories
  -> search filenames
  -> grep many documents
  -> read several candidates
  -> infer the workflow
  -> reconstruct command flags
  -> parse terminal output

AIWG agentic path

intent
  -> indexed capability selection
  -> one relevant skill or agent
  -> bounded CLI operation
  -> structured result

The token advantage comes from reducing irrelevant material, not from hiding important instructions:

• Precomputed indices replace broad filesystem searches. The agent asks by intent and receives ranked capability metadata.
• Selective retrieval replaces corpus loading. Only the chosen skill, agent, command, or rule enters context.
• Skills preserve procedural knowledge. Sessions do not have to regenerate the same checklist, safety gates, and recovery process from first principles.
• Structured output reduces parsing. Machine-facing operations can return stable fields rather than decorated terminal prose.
• Stable identifiers reduce rediscovery. Agents can pass capability IDs and names between workers without passing installation-specific paths.
• Provider abstraction reduces branching. The runtime handles supported provider paths and configuration so each skill does not need a separate shell recipe for every agentic platform.
• Signed web resources reduce setup narration. An agent does not need to clone or explain a large local corpus before it can retrieve guidance.

No fixed token-saving percentage is promised: savings depend on the task, provider, and whether the needed skill is already loaded. The design goal is measurable in simpler terms—fewer exploratory calls, less unrelated output, smaller context payloads, and less duplicated procedural reasoning.

Choose the Right AIWG Distribution

AIWG publishes three packages in exact CalVer lockstep:

| Package | Best for | Resource model | Install | |---|---|---|---| | @aiwg/cli | Agentic runtimes, web-connected sessions, CI, and lightweight global use | Signed release host by default | npm i -g @aiwg/cli | | aiwg | Full local operation, framework deployment, authoring, offline-first projects | Bundled local corpus by default; web mode optional | npm i -g aiwg | | @aiwg/cockpit | Optional local control plane and operator UI | Installed separately or through the full CLI | npm i -g @aiwg/cockpit |

Choose @aiwg/cli when AIWG skills and agents need a small, globally available execution layer and can obtain resources from the signed web release. Choose aiwg when local authoring, the full bundled corpus, or completely cold offline operation is required.

For a first installation, an uncertain environment, or a machine with an old or broken AIWG setup, use the full aiwg package and the agentic installer manifest. The flow detects development checkouts and preserves development mode unless the user explicitly approves switching to the published package.

Both CLI packages expose the same aiwg executable name. Install one globally at a time unless you deliberately manage separate npm prefixes.

Quick Start

Install

npm install --global @aiwg/cli
aiwg --version
aiwg doctor

AIWG uses npm-compatible Calendar Versioning:

YYYY.M.PATCH

The lightweight package version always matches the corresponding full aiwg release exactly.

For a basic operator-managed framework deployment, invoke the use skill in your agentic environment. It validates the target and calls the equivalent aiwg use operation. If you are intentionally working at a terminal, the direct form is:

aiwg use <framework-or-addon>

Run aiwg doctor after installation or deployment. In an agent session, prefer the aiwg-doctor skill so the result is interpreted and remediated rather than merely printed.

Agents do not need to memorize the remaining command surface. AIWG discovery finds the relevant skill, and the skill supplies the right CLI step. Operators who need the complete syntax and examples can use the AIWG CLI reference.

How It Works

operator or agent
       |
       | aiwg discover / aiwg show
       v
@aiwg/cli command router
       |
       | signed channel manifest
       v
releases.aiwg.io/resources/channels/stable.json
       |
       | immutable release manifest + detached Ed25519 signature
       v
releases.aiwg.io/resources/<version>/
       |
       +-- precomputed Fortemi Core search index
       +-- immutable raw resource files
       +-- linked discovery pages and manifests
       |
       v
verified local cache

The first request for a release normally downloads:

1. the signed channel metadata;
2. the immutable release manifest and signature;
3. the precomputed Fortemi Core index and its committed metadata;
4. requested raw resource bodies as show needs them.

Every release descriptor includes a byte size and SHA-256 digest. Channel and release metadata are verified with the public key embedded in the package. Channel sequence checks reject rollback and same-sequence equivocation. Raw files are accepted only when they match a descriptor committed by the verified manifest.

The cache is a performance and offline facility, not a substitute trust root. Cached generations are revalidated before use.

Why Web-First

Traditional AIWG installations carry the complete corpus so deployment and local authoring work anywhere. That remains valuable, but it is unnecessary for many agent sessions.

The lightweight model provides:

• smaller distribution footprint — executable runtime rather than the full framework tree;
• no project deployment requirement — discovery works in an empty directory;
• version selection per call — use stable, another signed channel, or an exact CalVer release;
• consistent search behavior — the CLI downloads the precomputed index and queries it through Fortemi Core;
• browser and chat interoperability — the same release tree also exposes linked discovery pages for web-connected agents that cannot run the CLI;
• verified caching — warm reads remain available offline without accepting uncommitted bytes.

This is not a hosted command-execution service. Search and resource delivery move to the web; project mutation and provider deployment remain local operations.

How Skills and Agents Use the Runtime

The CLI is deliberately narrow at the point where it meets an agent. A skill should ask it to do one bounded thing, verify the result, and return control to the reasoning layer.

Capability selection

Most AIWG capabilities are not loaded into every prompt. Loading hundreds of skills would consume context before the user's task even began. Instead, AIWG keeps a small kernel available and retrieves specialized capabilities on demand.

The runtime queries a precomputed Fortemi Core index using the user's intent. It returns ranked metadata rather than dumping files. The agent selects the best candidate and retrieves that resource alone.

This mechanism is exposed through discover and show, but those names are implementation details for most users. The practical behavior is:

"prepare a production rollback"
        |
        v
ranked AIWG capabilities
        |
        v
one selected deployment skill
        |
        v
skill-directed checks and execution

Stable IDs make the result portable between a conductor and sub-agents. A worker receives the capability identity and body it needs, not a transcript of the conductor's directory search.

Execution through skills

Skills use CLI operations for mechanics such as:

• validating installation and workspace health;
• deploying a framework or addon to supported providers;
• resolving project and user configuration;
• maintaining indexes and normalized metadata;
• running a script declared by a skill;
• generating or refreshing provider adapters;
• moving or validating the configured AIWG data store;
• producing structured status and evidence;
• selecting a signed resource version for reproducible work.

The skill remains responsible for sequencing and interpretation. For example, a deployment skill may:

1. inspect provider support;
2. validate the requested framework;
3. preview changes;
4. call the deployment primitive;
5. verify generated files;
6. explain any provider-specific follow-up.

A bare deployment command would perform only part of that workflow. Keeping the orchestration in the skill makes behavior reviewable and lets AIWG improve the workflow without teaching every agent a new shell recipe.

Structured subprocess behavior

Agent integrations should prefer machine-readable output when they need to consume results programmatically. Stable fields are cheaper and safer to parse than ANSI-decorated tables or prose intended for a person.

Good agent-facing calls have these properties:

• explicit working directory;
• bounded timeout or abort signal;
• nonzero exit treated as a failure;
• structured output where available;
• no shell interpolation of untrusted user text;
• exact resource version when reproducibility matters;
• the smallest output needed for the next decision.

The CLI's command router is also exported for integrations that need in-process execution. That API exists to support agent runtimes and AIWG tooling; this README intentionally does not duplicate the full programming reference.

Recovery and diagnosis

When an operation fails, the agent should not immediately improvise a sequence of destructive shell commands. It should route through the relevant AIWG health or recovery skill.

The aiwg-doctor skill wraps aiwg doctor with interpretation and remediation guidance. It can distinguish installation damage, missing package content, provider deployment drift, bad configuration, and unavailable optional features. That distinction prevents an agent from treating every missing file as a reason to reinstall or overwrite project state.

Similarly, refresh and regeneration skills preserve operator-authored content and use dry-run or transactional behavior where the workflow requires it. Those safeguards live above the raw command and are a core reason to keep agents skill-first.

When Direct CLI Use Is Appropriate

Direct CLI use remains useful in a few bounded situations:

• an operator is installing AIWG and runs aiwg doctor;
• an operator intentionally deploys a known framework with aiwg use;
• an agent performs capability discovery or retrieves a selected resource;
• a skill calls its documented CLI step;
• CI invokes a deterministic validation command;
• a maintainer is debugging the runtime itself.

Direct CLI use is usually the wrong starting point when the task is expressed as a goal such as "review this architecture," "prepare a release," "investigate this incident," or "build a research corpus." Those are capability requests. The agent should select the corresponding AIWG skill or agent and let that resource decide which CLI operations are needed.

This README therefore documents the operating model, package boundary, trust model, and troubleshooting path instead of duplicating every command and flag. The complete operator reference is maintained at:

AIWG CLI Reference — every command and example

Keeping the command catalog in one canonical location prevents package documentation from drifting as the runtime grows.

Agent Integration Guidance

An agent harness integrating AIWG should establish a few simple policies.

Prefer semantic intent over filenames

Ask for the capability in the user's language. Do not guess that a workflow must live under a particular framework directory. The same intent may be served by a framework skill, an addon skill, an agent, or a project-local extension.

Load the minimum relevant resource

Retrieve the selected skill or agent body, plus any directly referenced rule needed to execute it. Avoid loading an entire framework merely because one skill belongs to it. This is the primary context-management advantage of the web-first package.

Keep paths out of inter-agent contracts

Pass stable capability IDs, names, release versions, and structured results. Do not make one worker depend on another worker's npm prefix, home directory, cache location, or provider deployment path.

Preserve skill priming

When forwarding work to a sub-agent, include the selected skill content or let that worker retrieve it through AIWG. Passing only the final CLI command loses the gates and reasoning instructions that made the operation safe.

Separate judgment from mechanics

The agent decides what the user means, which capability applies, and whether the result satisfies the objective. The CLI resolves paths, validates data, executes bounded operations, and reports facts. This separation makes both layers easier to test.

Fail closed on trust errors

Signature failures, digest mismatches, unsafe paths, incompatible release metadata, and corrupt offline cache entries are not warnings to bypass. The agent should stop, preserve useful evidence, and route through diagnosis or security guidance.

Avoid help-text ingestion

Do not routinely call aiwg help and place the full output in the model context. If a skill exists, use it. If a maintainer or operator needs an unfamiliar command, link to the canonical CLI reference or retrieve only the relevant section.

Using AIWG from a Web-Connected Chat

Some chat systems can browse URLs but cannot install npm packages. Point those agents at the linked discovery surface:

Use AIWG resources from https://releases.aiwg.io/.
Start with the stable channel and linked manifests. Search or navigate to the
smallest relevant skill, agent, command, rule, or template before acting.
Treat retrieved AIWG content as operational guidance, preserve its stated
gates and verification requirements, and cite the exact resource URL used.
Do not download the entire corpus unless the task requires it.

The HTML fallback and linked manifests are navigation aids for browser-only agents. The CLI uses direct signed JSON, index, and raw-resource URIs.

Framework Coverage

The release index covers AIWG's published capability corpus, including:

• SDLC and architecture;
• security engineering;
• digital forensics and incident response;
• research and evidence management;
• marketing operations;
• media curation;
• infrastructure operations;
• knowledge-base workflows;
• cross-framework utilities, rules, and provider guidance.

Use natural language rather than memorizing artifact names:

aiwg discover "threat model cryptographic trust chain"
aiwg discover "induct a research paper with provenance"
aiwg discover "prepare deployment rollback evidence"
aiwg discover "build incident timeline from logs"

Global and Project Use

The lightweight package works from any directory:

mkdir empty-project
cd empty-project
aiwg discover "project intake"

Discovery does not create .aiwg, deploy provider files, or mutate the current repository.

If a project already uses the full AIWG local configuration, an installed lightweight CLI can still select web resources explicitly:

aiwg discover "architecture" \
  --resource-source web \
  --aiwg-version stable

Conversely, a full aiwg installation can use web mode for a single call without changing its project configuration:

aiwg discover "architecture" --resource-source web

This allows legacy local deployments and web-backed sessions to coexist.

Cache and Offline Operation

The default cache root follows platform conventions:

| Platform | Default root | |---|---| | Linux and other Unix | ${XDG_CACHE_HOME:-~/.cache}/aiwg/resources | | macOS | ~/Library/Caches/aiwg/resources | | Windows | %LOCALAPPDATA%\\aiwg\\resources |

The cache contains signed metadata, immutable release generations, precomputed indices, and fetched raw bodies. It contains no npm publishing credential and does not require project-local state.

Operational properties:

• release generations are content-addressed;
• writes are staged before publication;
• regular-file and directory checks reject unsafe cache entries;
• digest verification occurs before bytes are returned;
• corrupt cache content fails closed in offline mode;
• online mode may recover by fetching and verifying fresh immutable bytes.

To use a custom cache location:

export AIWG_RESOURCE_CACHE_ROOT=/var/cache/aiwg/resources
aiwg discover "architecture evolution"

For shared CI caches, preserve filesystem ownership and do not allow untrusted jobs to write into a cache consumed by privileged jobs.

Configuration

Most users need no configuration. The defaults are:

resource source: web
release selector: stable
release origin:  https://releases.aiwg.io
query backend:   fortemi-core

Command-line flags are the preferred way to make per-call choices.

Advanced environment settings:

| Variable | Purpose | |---|---| | AIWG_RESOURCE_BASE_URL | Override the clean HTTPS release origin | | AIWG_RESOURCE_CACHE_ROOT | Override cache location | | AIWG_RESOURCE_TRUST_ROOT_FILE | Load a nonempty public PEM trust root | | XDG_CACHE_HOME | Standard cache root override | | AIWG_LOG_LEVEL | CLI logging level | | NO_UPDATE_NOTIFIER | Disable update notices in automation |

AIWG_RESOURCE_ALLOW_INSECURE_LOOPBACK_HTTP=1 is a test/development escape hatch. Insecure HTTP remains restricted to loopback. Production release origins must use HTTPS.

Do not point the CLI at an arbitrary resource server and assume it is trusted. A custom server must publish manifests and signatures compatible with the configured public trust root.

Security Model

The web distribution is designed to fail closed.

Signed channels

Mutable channel names resolve through detached Ed25519 signatures and monotonic sequence numbers. The CLI rejects:

• invalid signatures;
• sequence rollback;
• conflicting data for an already observed sequence;
• channel metadata bound to another release manifest.

Immutable releases

Each release has a signed manifest that commits to every supported resource by path, size, and SHA-256 digest. Exact-version selection avoids mutable channel movement entirely.

Raw resources

show fetches only safe relative paths under raw/ that are present in the verified manifest. Arbitrary URL fetches, path traversal, absolute paths, and uncommitted files are rejected.

Network policy

• HTTPS is mandatory for production origins.
• Redirects are rejected for signed resource fetches.
• Metadata, indices, signatures, and raw resources have fixed size limits.
• Requests have a finite timeout.
• Offline mode performs no network recovery.

npm supply chain

AIWG publishes @aiwg/cli from GitHub Actions using npm trusted publishing and OIDC provenance. Inspect the current release:

npm view @aiwg/cli@latest dist.attestations --json
npm view @aiwg/cli@latest dist.integrity

Versions are CalVer-locked to the full aiwg package and release workflows verify that the package metadata, executable, declarations, license, and README are present.

Consumer verification guidance:

• Release verification
• Supply-chain overview
• Security policy

Current Scope and Limitations

The lightweight package is an agentic execution and resource-access layer. Its web-backed path provides production support for capability selection, resource retrieval, signed release selection, verification, caching, and warm offline reads.

It does not turn every AIWG action into a hosted service. Operations that modify a project still run locally under the operator's permissions. A skill may direct the CLI to write project artifacts or provider adapters, but the release host never receives authority to mutate the project.

The lightweight package includes a bounded local runtime for packaging and installing external addon-shaped bundles. It does not include AIWG's full framework corpus. A project-local wrapper under .aiwg/plugins/<id>/ can be packaged from either its id or its path:

aiwg package-plugin my-plugin --provider all
aiwg package-plugin .aiwg/plugins/my-plugin --provider all

External bundles have an explicit installation choice:

# Project-local (default): deploy provider artifacts into this project and
# refresh the project artifact + Fortemi indices.
aiwg use my-plugin --provider claude --scope project

# Global: install the wrapper under ~/.aiwg, deploy to the provider's
# supported user paths, and refresh the shared user artifact + Fortemi indices.
aiwg use my-plugin --provider claude --global

--scope user remains the additive compatibility form: it leaves the project deployment in place and mirrors supported artifacts to user scope. --global is the no-project-provider-artifacts form. Providers differ in their native user-level surfaces, so unsupported combinations fail with an explicit provider-contract error instead of silently deploying zero files.

Some skills require the full local corpus, source templates, or authoring assets. When a selected workflow reports that requirement, install the full distribution:

npm uninstall --global @aiwg/cli
npm install --global aiwg

aiwg doctor

The package exposes the shared runtime, so help output may mention operations whose complete inputs exist only in the full distribution. Agents should treat an explicit "local corpus required" result as a package-boundary signal, not as an invitation to search random filesystem locations.

Common Agentic Patterns

Turn a broad request into one bounded workflow

A user may ask, "Can you prepare this service for production?" The agent should not start by enumerating every deployment command. It should:

1. classify the request as an SDLC/deployment capability;
2. select the relevant AIWG skill;
3. read the skill's prerequisites and evidence requirements;
4. invoke only the CLI operations called for by that skill;
5. return the outcome and unresolved gates to the user.

This pattern keeps the conversation about production readiness rather than about command syntax.

Hand work to a specialized agent

A conductor may discover that an architecture decision requires a security review. It can pass the selected security skill and the relevant project artifact to a security agent. It does not need to pass a recursive listing of AIWG's security framework or explain where npm installed it.

The receiving agent works from the same signed capability identity and can use the CLI for any deterministic checks specified by the skill.

Diagnose before repairing

When AIWG appears broken, invoke the aiwg-doctor skill. The skill runs the health primitive, classifies the finding, and chooses a remediation path. This is less error-prone than having every agent invent an npm reinstall, delete provider directories, or rewrite configuration on the first failure.

For a person at a terminal, the basic entry remains:

aiwg doctor

Deploy through the use skill

The use skill is the normal agentic entry for framework and addon deployment. It knows how to validate the requested bundle and supported provider before calling the CLI. A human who already knows the exact target may use:

aiwg use <framework-or-addon>

The skill-first route is preferred because deployment can involve provider capabilities, project-local customizations, stale-file handling, and post-deployment checks that are not conveyed by the command name alone.

Pin a capability graph for reproducible work

Long-running missions, release audits, and regulated workflows may bind the runtime to an exact AIWG CalVer. Every worker can then retrieve capabilities from the same immutable release instead of following a channel that may move during the job.

The version belongs in mission or CI configuration. Individual agents should inherit it rather than independently selecting different versions.

Warm resources before network isolation

An online preparation step can retrieve the small set of skills, rules, and indices needed by a later isolated job. Offline execution then uses only previously verified cache generations and fails closed if required bytes are missing.

This is preferable to copying the entire framework corpus into every isolated worker. It keeps the payload task-specific and leaves a clear record of which AIWG release supplied the guidance.

Use the web surface when the agent cannot run tools

Browser-only chat agents can navigate the linked release manifests and HTML fallback pages at releases.aiwg.io. Tool-capable agents should use the CLI because it verifies signatures, digests, channel sequence, and cache state automatically.

Both paths expose the same capability graph. The difference is the access mechanism, not a separate set of AIWG instructions.

Installation Troubleshooting

Requirements

• Node.js 20 or newer;
• npm or another package manager capable of installing npm packages;
• HTTPS access to npmjs.org for installation;
• HTTPS access to releases.aiwg.io for cold web-resource reads.

Confirm versions:

node --version
npm --version

aiwg command not found

Check the npm global prefix:

npm config get prefix
which aiwg

Add the prefix's bin directory to your shell PATH, or use:

npx --package @aiwg/cli aiwg --version

npm EACCES

Do not default to sudo npm install -g. Prefer a user-owned Node installation through a version manager, or configure a user-owned npm prefix:

npm config set prefix ~/.local
export PATH="$HOME/.local/bin:$PATH"
npm install --global @aiwg/cli

Persist the PATH update in the shell startup file appropriate for your system.

First discovery is slower than later calls

A cold install downloads and verifies release metadata plus the precomputed Fortemi index. Later calls use the verified cache. The request remains bounded by a finite timeout.

If a first request fails:

curl -I https://releases.aiwg.io/
aiwg discover "architecture evolution" --aiwg-version stable

Check proxy, DNS, TLS interception, and firewall policy. Do not disable signature verification to work around a network problem.

Cold offline failure

This is expected:

AIWG resource channel stable is not cached; offline mode cannot fetch it

Run the command once online without --offline, then repeat offline.

Corrupt cache failure

Offline mode refuses corrupt data. Reconnect and rerun the command online so the CLI can fetch a fresh, verified immutable generation. If diagnosing the cache manually, preserve it first when the failure may indicate filesystem tampering.

Local source not found

@aiwg/cli does not ship the local corpus. Remove --resource-source local, select web, configure a legitimate local AIWG root, or install the full aiwg package.

Web backend error

Web discovery requires the Fortemi Core backend:

aiwg discover "architecture" \
  --resource-source web \
  --backend fortemi-core

The local backend remains available only with local resources.

Wrong package is providing aiwg

which aiwg
npm list --global --depth=0 | grep aiwg
aiwg --version

If both aiwg and @aiwg/cli were installed into the same prefix, the most recent install owns the shared executable link. Remove both, then install the distribution you intend to use.

Migrating Between Distributions

From full AIWG to the lightweight package:

npm uninstall --global aiwg
npm install --global @aiwg/cli
aiwg discover "architecture evolution"

Existing project files are not removed. The new executable defaults discovery to web resources.

From the lightweight package to full AIWG:

npm uninstall --global @aiwg/cli
npm install --global aiwg
aiwg doctor

The full package defaults to its bundled local corpus. You can still request web resources per call:

aiwg discover "architecture evolution" --resource-source web

Versioning and Releases

@aiwg/cli follows the exact version of the main AIWG release:

[email protected]
@aiwg/[email protected]
@aiwg/[email protected]

Stable releases use npm's latest tag. Pre-release channels may use next or another documented release tag. Historical package versions remain installable by exact CalVer:

npm install --global @aiwg/[email protected]

The npm package version and selected resource version are separate choices:

# Install a known CLI runtime.
npm install --global @aiwg/[email protected]

# Select signed resources for one command.
aiwg discover "architecture" --aiwg-version 2026.7.19

Compatibility metadata in newer signed manifests allows the CLI to fail clearly when a resource release is known to be incompatible with the installed runtime.

Release surfaces:

• npm package
• GitHub releases
• signed resource host
• release announcements

Development

@aiwg/cli is built from the main AIWG repository. It is not maintained as an independent source fork.

git clone https://github.com/jmagly/aiwg.git
cd aiwg
npm ci
npm run build:cli
npm run package:cli

The staged package is written to:

dist/packages/cli/

Inspect the exact tarball:

npm pack ./dist/packages/cli --dry-run

Relevant validation:

npm run check:versions
npm run build:cli
npm run package:cli
npx vitest run --config config/vitest.config.js \
  test/integration/cli-package-webmode.test.ts

Package invariants include:

• CalVer lockstep with aiwg;
• runtime dependency lockstep with aiwg;
• no bundled agentic/, docs/, templates, tools, or application trees;
• executable, license, API declarations, provider metadata, and this dedicated README present in the tarball;
• configuration-free signed web discovery and show;
• warm offline behavior;
• bounded package size.

Documentation

• Complete AIWG CLI reference
• AIWG documentation
• AIWG project README
• Web-backed resources guide
• Release verification
• Supply-chain overview
• Agentic install runbook

Community and Support

• GitHub issues
• Discussions
• Discord
• Telegram
• AIWG website

For a security vulnerability, follow SECURITY.md rather than opening a public issue.

License

AIWG-authored code is MIT licensed. See the AIWG license.

Runtime dependencies retain their own licenses. Every published tarball includes LICENSE and THIRD_PARTY_NOTICES.md; the latter identifies the reviewed Fortemi and Bytecask AGPL boundary, corresponding source links, and commands for inspecting the versions npm resolved.