Reference: Set up

Reference for the "Set up" group of qargi commands: every verb with its arguments, options and examples, generated from the release.

Updated 2026-11-05

qargi project #

Store the answers about a project, once, outside the repository.

The answers are the repository, its long-lived branches, the roles that exist (build, write, review, test) with each role's base branch, model, effort, packages and skills, the memory stores, the budget, and optionally a lead with teams and a push grant. Provisioning and dispatch read them. Push policy per role is none: an agent never pushes; the lead's grant is separate (qargi help push).

qargi project template #

qargi project template NAME

Print an answers file with defaults.

Edit it, then store it with init. models.provider is empty and must be set (the provider the project's agents run on; there is no default); project validate reports it while it is not. No role names a model: it takes the provider's tier once one is set.

qargi project init #

qargi project init NAME [OPTIONS]

Validate and store an answers file.

qargi project template acme > acme.json
qargi project init acme --answers acme.json

qargi project new #

qargi project new NAME [OPTIONS]

Start a new project: its directory, a git repository on the methodology's branches and generic files.

Prints the plan (directory, branches, files, deployment options with instructions) and a token; with --plan and --approved it creates the directory, runs git init, writes the generic files in a first commit and creates the long-lived branches. Nothing is pushed and no remote is created: say where it goes with git. The files mention no tool of yours. They include an AGENTS.md with a Development environment section and a Makefile with stub bootstrap and doctor targets (the doctor fails until you fill it in); see qargi help environment.

qargi project new acme --param test_command='make test'
qargi project new acme --dir ~/src/acme --url https://github.com/me/acme

qargi project attach #

qargi project attach [DIR] [OPTIONS]

Attach to an existing repository: read it, show the answers and the gaps, store on approval.

Reads the repository (branches, tags, version and changelog files, test command, CI) and changes nothing in it. Prints the answers it would store, the gaps against the methodology and what it could not determine, and a plan token. With --plan and --approved it stores the answers outside the repository. The safe gaps are closed by qargi project adopt, the rest by hand. It reads the tree of the methodology's integration branch (develop), else of the default branch, else of HEAD, and says which; never the working tree. It prints origin as read and the https url it normalises to. If answers are already stored it shows stored against detected, lists the fields the stored file lacks, stays read-only and gives no plan token; with --force the plan replaces what it detects and keeps what it cannot (the roles' models and effort, cloud, memory, budget). It reports what it found of the development environment (section, task runner, bootstrap and doctor commands) and lists the pieces that are missing as gaps. It never guesses a provider: models.provider (and the roles' models) are stored only with --provider NAME, and without it the output says so; with --force --provider fills in a provider that is not set and never replaces one.

qargi project adopt #

qargi project adopt [NAME] [OPTIONS]

Adopt an attached repository: create the missing long-lived branches and the missing methodology files on a branch to review.

Prints the plan and a token: the local branches it would create (at the default branch tip; main stands for master; none is moved) and the files from the methodology that do not exist, written as one commit on agent/adopt-NAME cut from develop. With --plan and --approved it creates exactly that. Existing branches and files are never changed, nothing is pushed or checked out, and a second run finds nothing to do. Changelog format, tag format and CI content are listed as left for you, and so are the bootstrap and doctor targets a repository with a task runner lacks (an existing file is not edited). The AGENTS.md section it drafts names the repository's own runner. Refused (exit 2) with a dirty working tree, a detached HEAD, no commits, a project that is not attached, and in a member run.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi project adopt acme
qargi project adopt acme --plan TOKEN --approved "go ahead"

qargi project set #

qargi project set [NAME] PATH VALUE

Change one answer.

PATH is dotted (budget_cents, roles.write.effort, lead.push); VALUE is JSON or a plain string. models.extensions and models.accept_no_barrier are refused here: they change only through qargi provider enable|disable and qargi provider accept. roles.ROLE.tools is the list of the tools a role needs beyond its apt packages, each {kind, name, ...}: kind go (name a package path, version a tag: go install NAME@VERSION), kind binary (name the file name, version, url of the file itself, sha256 of it: downloaded to ~/.local/bin and kept only when the hash matches) and kind submodule (name as in .gitmodules, path: checked out in each member clone by qargi local prepare). env plan lists them, env apply installs them and env check reports one that is missing or wrong; a member's guard refuses setting them (and a whole role), as it refuses release.*, test_command, env.* and site.*.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi project set acme roles.write.effort high
qargi project set acme packs.none true
qargi project set acme roles.test.tools '[{"kind":"go","name":"acme.test/ci","version":"v1.2.0"}]'

qargi project show #

qargi project show [NAME]

Print the stored answers and what they mean.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi project list #

qargi project list

List the stored projects.

qargi project validate #

qargi project validate FILE

Check an answers file without storing it (a WARN line for each pack linked to a role that is not in the pack library, and for a profile that still carries the shipped template header).

qargi project profile #

qargi project profile SUBCOMMAND [NAME] [OPTIONS]

Check the repository's profile: the shipped template header, and gate commands the repository does not know (check).

Read only, so a member may run it. check reads the profile (the gates, rules and review steps of a repository, outside the repository) and prints FAIL for each line at the top that is still the shipped example's (the Example profile title and the Copy to line of examples/myproject/profile.md), exit 1; and WARN for each backticked command in its Gates section that is found in none of the repository's instruction files and Makefile targets (a make target of the Makefile, the command's text in one of the three files, or a script that exists), exit 0. No profile is fine (said, exit 0); a --profile file that is not there is exit 2. Without NAME the project is the one in effect, else the repository of the current directory. project validate prints the header finding as a WARN line.

qargi project profile check acme
qargi project profile check --profile ./profile.md

qargi project link #

qargi project link [PROJECT] [OPTIONS]

Make this work tree load the project's skills, agents and memory from ~/.qargi.

One plan and one token for every resource, each placed and linked the way the project's runtime says (a directory link, one link per entry, or a copy). A real directory in the way is moved to NAME.qargi-backup, never deleted. Run it inside a work tree to link that one; nothing records which work trees exist. A member's guard refuses it.

qargi project unlink #

qargi project unlink [PROJECT] [OPTIONS]

Undo project link in this work tree and restore the backups.

qargi methodology #

List and inspect the development and release methodologies.

A methodology is the way a project is developed and released, as data: its branches, versioning and changelog, test tiers, CI, release steps and deployment options, and the generic files a new project starts with. One ships with qargi (gitflow); add your own under ~/.qargi/config/methodologies/NAME/ (methodology.json and a scaffold/ directory). These verbs only read; qargi project new and adopt write, and only after a plan.

qargi methodology list #

qargi methodology list

List the methodologies and where they live.

qargi methodology show #

qargi methodology show NAME

Print a methodology: branches, tests, CI, release steps, parameters, scaffold, deployment options.

qargi methodology check #

qargi methodology check [NAME]

Validate one methodology, or all of them.

qargi methodology files #

qargi methodology files NAME [OPTIONS]

Print the scaffold rendered with the parameters, writing nothing.

qargi methodology files gitflow --param project=acme --param test_command='make test'

qargi methodology deployment #

qargi methodology deployment NAME [ID]

List the deployment options, or print one option's instructions.

qargi cloud #

Which ant profile and workspace each project uses.

A project can be bound to an ant profile and the workspace that profile must reach (the project's optional cloud answer). Every qargi command about that project then runs ant under that profile, and a cloud call is refused if the profile no longer reaches the workspace, so work never lands in another project's workspace. A project without a binding uses ant's active profile. qargi stores and checks the binding; it never reads or writes a token. login runs ant auth login on your terminal; a member or a script cannot.

qargi cloud list #

qargi cloud list

Print every project's binding.

qargi cloud show #

qargi cloud show [PROJECT]

Print one project's binding.

qargi cloud set #

qargi cloud set [PROJECT] [OPTIONS]

Bind a project to an ant profile and a workspace.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi cloud unset #

qargi cloud unset [PROJECT]

Remove a project's binding.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi cloud check #

qargi cloud check [PROJECT]

Check that the profile exists and reaches the workspace (reads the ant profile only).

qargi cloud login #

qargi cloud login [PROJECT]

Log the project's profile in, bound to its workspace (your terminal only).

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi agent #

Name the members: the local agents that do the work.

A member is a local agent you name, rendered from the one member definition qargi ships, with the roles it serves: build, write, review, test (all four by default). The render is kept in the configuration directory (agents/PROJECT/NAME.EXT beside agents.json, outside every repository) and written from there to the runtime's agents location; a checkout cleaned or cloned afresh gets it back with agent refresh. The task block names the role and carries its role text (roles/<role>/ROLE.md); there is no skill to load. Review is read-only as a rule: the guard refuses changes to the clone under that role. Under every role it refuses the verbs that change a skill (qargi skill|tool new, import, seal, remove, link, unlink, enable, disable; qargi discover install; qargi packs apply) and writes in the pack library, the credentials directory and install.json, ~/.claude/skills and any .claude/skills directory; it fails closed. Dispatch spawns the member qargi agent for ROLE prints.

qargi agent add #

qargi agent add NAME [OPTIONS]

Create a member under a name you choose.

A member belongs to a project, and the definition is rendered by the provider of that project. Refuses a name that exists, a name that is not kebab-case, the name of a built-in agent type of that provider, no --project (exit 2), and a project with no provider (exit 2: there is no default provider). Nothing is written to a runtime's user-level directory.

qargi agent add forge --roles build,test --project myproject
qargi agent add scribe --roles write --model opus --project myproject
qargi agent add worker --project myproject    # the write-class base: build, write and test

qargi agent list #

qargi agent list [OPTIONS]

List the members of every project, their roles and definitions.

One row per member, with no header line: PROJECT, NAME, ROLES (comma separated), MODEL/EFFORT, FILE, then in brackets MISSING (the runtime's file is gone), STALE (the copy in the configuration directory is gone or changed, or the definition, catalog, renderer or an extension changed since the render) or DRIFT (the file was edited by hand), each followed by the command that fixes it: qargi agent refresh NAME --project P. Members are kept per project, so two projects can each have a worker.

qargi agent rename #

qargi agent rename OLD NEW [OPTIONS]

Rename a member and its definition.

Within its project. The project is --project, else the one in effect, else the only project that has a member OLD; a name two or more projects hold, with none named or in effect, is refused (exit 2) and lists them.

qargi agent refresh #

qargi agent refresh NAME [OPTIONS]

Re-render a member from the member definition qargi ships now.

The project is found as for rename. Keeps its name, roles and model, and writes the copy in the configuration directory and the runtime's file again: a file that is gone (a cleaned checkout, a fresh clone) comes back, a file edited by hand is replaced (the output says so). Use it after an upgrade changes the definition (for example its hook); an unchanged member is left alone. Sessions started afterwards use the new definition.

qargi agent models #

qargi agent models [OPTIONS]

Show the base members, the profiles with their resolved models and efforts, and each member.

Two base members, one per guard class: worker (build, write, test; may write) and reviewer (review; read-only). Everything else is a profile {base, tier, effort, purpose} resolved at dispatch: the shipped ones are in lib/model-defaults.json (build, write, test, review, auditor, advisor, researcher, lead), a project adds or overrides its own under profiles.NAME in its answers, and a provider file (lib/providers/NAME.json; the project's models.provider) maps the tiers fast, balanced, deep and frontier to models. The frontier tier (researcher) is opt-in. Problems are flagged on their row, never fatal: a member that is not a base (nothing dispatches it), a missing base, a refused project profile, a mixed-class member, a tier with no alias, a frontier member outside researcher. A project is needed, because its models.provider decides the models: --project, else the one in effect (with none, exit 2). The members shown are that project's (`agent list` shows all projects'). Read-only.

qargi agent remove #

qargi agent remove NAME [OPTIONS]

Delete a member's definition and its record.

The project is found as for rename: --project, else the one in effect, else the only project that has the member; a name in two or more projects with none named is refused (exit 2).

qargi agent for #

qargi agent for ROLE [OPTIONS]

Print how to dispatch a role: the base member, the model alias and the effort.

The base member is the one the profile names (worker for build, write and test, reviewer for review) when the project has registered it; no other member serves, and without it the verb says which base to add. A read-only role never resolves to a member that can write. Plain output is one line: MEMBER MODEL EFFORT PROFILE; pass MODEL and EFFORT to the Agent tool with the member as subagent_type.

qargi role #

List and check the roles: what a member or cloud agent is for.

A role is a directory with role.json (its class, write or read-only, and a description) and ROLE.md (its instructions). Four ship with qargi: build, write, review and test (review is read-only). Add your own under ~/.qargi/config/roles/NAME/: a name of one lower-case token, never lead. The class decides what the guard allows a member (read-only: nothing in the clone changes); the text of a role cannot change it. A task block carries the role's text; a cloud agent of the role has it in its system prompt.

qargi role list #

qargi role list

List the roles, their class and where they live.

qargi role show #

qargi role show NAME

Print a role: its class, description and instructions.

qargi role prompt #

qargi role prompt NAME

Print a role's instructions as a task block carries them.

qargi role check #

qargi role check [NAME]

Validate one role, or all of them.

qargi provider #

List and check the model providers: tiers, models and what each can do.

A provider is a descriptor, lib/providers/NAME.json, with one schema for every provider: the model each tier (fast, balanced, deep, frontier) maps to, with the date and source it was verified, the effort levels it understands, the one surface it serves (local or cloud) and a capability matrix for it: model and effort overrides at dispatch, a fixed tool list per agent, a read-only barrier, a session budget ceiling, memory stores, skills and MCP. A capability that is not verified counts as not supported. A provider with no read-only barrier on its surface cannot serve the review role there unless you accept that with qargi provider accept. The project's models.provider chooses the provider; there is no default, and a verb that needs one refuses a project with none (exit 2). A family name (what several runtimes of one vendor share) stands for the runtime of a surface only in a project's models.provider and in provider of; every verb that takes a NAME (show, check, model, addenda, adapter-run, effective, require-barrier, layout, launch, require-skills) takes a runtime name, and a family name is refused as an unknown provider.

qargi provider list #

qargi provider list

List the providers with the surface each serves and whether the descriptor is clean.

qargi provider show #

qargi provider show NAME [OPTIONS]

Print one provider: tiers and models, effort levels and its capability matrix.

qargi provider accept #

qargi provider accept NAME [OPTIONS]

Record that you accept a provider surface that has no read-only barrier.

Without --plan and --approved it prints what would be recorded and a plan token. Applied, it writes models.accept_no_barrier.SURFACE (who, when, why) to the project's answers and the audit log. It is the only way a provider surface whose read-only barrier is not supported can serve the review role.

qargi provider check #

qargi provider check NAME|DIR [OPTIONS]

Validate a definition (a library name or a directory) and say what degrades.

Fails on a definition that breaks the schema, a name that differs from its file, a missing tier or an unknown capability. Warns on a verified date that is missing and says which capabilities count as not supported because of it, and which roles therefore cannot be served (for example review where the read-only barrier is not supported).

qargi provider new #

qargi provider new NAME [OPTIONS]

Scaffold a provider, catalog or extension pack in the library.

Plan, token, approval, as for a skill. The pack is stored unsealed and counts for nothing until sealed.

qargi provider import #

qargi provider import SOURCE [OPTIONS]

Import a provider pack from a directory, a JSON file or an https git URL, after a review.

The review lists files, executables (with hash and interpreter), URLs, network commands and secret findings. Binaries, archives, symlinks and secrets are refused; opaque blobs are flagged. A pack with executables also needs --approve-exec naming each. Stored sealed, never enabled; a shipped or existing name is refused.

qargi provider seal #

qargi provider seal NAME [OPTIONS]

Record the current content of a library provider pack as approved.

qargi provider remove #

qargi provider remove NAME [OPTIONS]

Remove a library provider pack.

qargi provider enable #

qargi provider enable [PROJECT] EXTENSION [OPTIONS]

Let a project use a library extension pack.

An extension adds resources or capabilities to a runtime for one project. It counts only once it is sealed and verified.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi provider disable #

qargi provider disable [PROJECT] EXTENSION [OPTIONS]

Stop a project using a library extension pack.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi provider adapter-run #

qargi provider adapter-run NAME SURFACE VERB [OPTIONS]

Run one verb of a runtime's adapter (a library pack's adapter runs only as a sealed private copy, removed afterwards).

NAME is a runtime name, not a family name. A verb the definition does not list exits 3.

qargi provider addenda #

qargi provider addenda NAME SURFACE

Print the texts a runtime's definition adds to the member contract (a cloud agent's prompt, or the run's contract directory on the local surface).

NAME is a runtime name, not a family name. resources.contract_addenda of the definition: plain text files in its own directory, printed in the order it lists them; nothing when it lists none. A file that is missing, is not text or leaves the directory is refused.

qargi provider notes #

qargi provider notes [TOPIC] [OPTIONS]

Print a note of the project's runtime (local unless --surface cloud), or list the topics it has.

The notes of a runtime's definition say how it does what a skill asks of it (how a lead starts a member, where it keeps its skills). With a TOPIC the text is printed; without, the names of the topics, one per line. The definition is the runtime's composed with the project's enabled extensions. A topic the runtime does not have, or a runtime with no notes, is exit 1, naming both and listing the topics there are; a project with no runtime on the surface, or a runtime that cannot be used as it stands (a library pack not sealed or changed since it was sealed, an unreadable definition), is exit 2 (a refusal; there is no default). Read-only.

qargi provider model #

qargi provider model NAME SURFACE TIER

Print the model a runtime maps a tier to on a surface.

NAME is a runtime name, not a family name.

qargi provider attest #

qargi provider attest NAME CAPABILITY [OPTIONS]

Record a capability you verified by hand or by a paid run (never runs or spends anything itself).

Asked each time: without the facts it prints what it needs and why. A failed result removes the earlier record.

qargi provision #

Create the cloud agent, deployment and environment of an instance.

Renders the agent, the shared environment, the memory stores it attaches and a manual-run deployment, shows the plan, and creates them only with your go-ahead. Names follow qargi help naming. Provision the role agents first; the lead (PROJECT-lead) needs them to exist. When the project's repository is on this host and declares a bootstrap command, plan also prints it as suggested text for the environment's setup script; it is only printed, never run.

qargi provision plan #

qargi provision plan [NAME] [OPTIONS]

Render the files and print the plan (changes nothing).

qargi provision plan acme-write

qargi provision apply #

qargi provision apply [NAME] [OPTIONS]

Create the resources of an approved plan.

Brings new memory stores to the canon, seeds the roles, records the ids and registers the instance.

qargi provision add-reference #

qargi provision add-reference NAME [OPTIONS]

Create and attach a reference store to an existing instance.

qargi env #

What a repository declares about its development environment.

qargi defines no file for this. A project declares its environment with a section of AGENTS.md (or README.md) headed Development environment, Environment or Setup, the version pins in the standard files, and two runnable targets: bootstrap (install or update, idempotent) and doctor (check only). qargi reads them; see qargi help environment.

qargi env show #

qargi env show [OPTIONS]

Print what was found (section, pins, submodules, runner, targets) and the commands in effect.

Read-only, and a member may run it. Nothing is executed: make, just, task and mise are never run, their files are read as text (at most 1 MB each; a symbolic link that leaves the repository is refused). The commands are derived from the targets (make bootstrap, make -n bootstrap, make doctor) and replaced by the project's answers env.doctor_command, env.bootstrap_command and env.dry_run_command; env.known_failures lists doctor lines accepted on this host. Each line says where it came from.

qargi env show
qargi env show --project acme --json
qargi project set acme env.doctor_command 'make doctor'

qargi env check #

qargi env check [OPTIONS]

Run the project's doctor, add the qargi layer (links, members, packs, memory) and print ENV OK or ENV INCOMPLETE.

A member may run it. It RUNS THE PROJECT'S CODE: the doctor command (env.doctor_command, else the doctor or check target) is run once, without a shell, in the repository, with standard input closed and a minimal environment, so the repository is as trusted as it is for test_command. Its lines are read: one that begins with missing, fail, error, not ok, stale, [x] or a cross mark, or ends with missing, not found or not installed, is a missing item; one that begins with expected or contains an env.known_failures entry is expected and not red; a non-zero exit with no such line is one missing item. With no doctor command a built-in minimum runs: submodules initialised, tags present when the repository has a remote and releases, and every tool a pin file names found on PATH, answering --version and matching the pin's major.minor (this runs TOOL --version). For a stored project it then checks the tools the roles declare (roles.ROLE.tools): a go tool or a binary that is not installed, is another version (go version -m) or another file (sha256) or sits in a directory PATH lacks, and a declared submodule that is not initialised or at another commit, are missing items. It adds, read-only, whether the checkout loads the project's skills, agents and memory, whether the members are current (STALE, DRIFT), packs check and memory check. The last line is ENV OK or ENV INCOMPLETE: N missing (...); exit status 0, 1 or 2 (usage, no such project, no repository). The verdict, HEAD, time and commands are recorded under check in state/env/PROJECT.json (mode 600, the other keys are kept); no command output is.

qargi env check
qargi env check --project acme --timeout 60
qargi env check --repo ~/src/acme --json

qargi env plan #

qargi env plan [OPTIONS]

Run the dry run of the bootstrap, show it grouped by privilege, print a plan token (the lead's; runs project code).

A dry run is not harmless: make -n still expands $(shell ...) and runs recipe lines marked + or holding $(MAKE), and the dry run of the other runners evaluates project code too. So the plan itself runs project code, and needs --approve-exec naming the executable; read the project's files first. The command runs without a shell, in the repository, with standard input from /dev/null, a minimal environment (PATH with absolute entries, HOME, USER, LOGNAME, LANG, LC_ALL, LC_CTYPE, TERM, TZ, TMPDIR) and a limit of QARGI_ENV_TIMEOUT seconds (default 120). Its output is shown line by line, the privileged lines (a command in the line is sudo, doas, pkexec, su or run0) apart from the others, then the executables seen in the lines. Lines and executables are read from the text, best effort: a recipe can run more than its dry run shows. Then the tools the roles declare (roles.ROLE.tools), each with its state here (ok, missing, wrong, path: in a directory PATH lacks); apply installs the go tools and binaries that are missing or wrong, so the token line names go in --approve-exec when a go tool is among them. The plan token is a hash over the output, the commands, the tools, the repository and its HEAD, and the host name. A member's guard refuses it.

qargi env plan --approve-exec make
qargi env plan --project acme --approve-exec make

qargi env apply #

qargi env apply [OPTIONS]

Run the bootstrap command once, for a plan you showed (the lead's).

Runs the dry run again (project code, as plan does) and refuses when its token is not --plan, when --approve-exec does not name the two executables, and when the plan has privileged lines and --allow-root is not given. Then the bootstrap command runs once, without a shell, with the minimal environment of plan and with standard input, output and error inherited, so sudo can ask on your terminal: run it in a terminal you are at. No password is read or kept. Apply writes two lines to the audit log (start and result, with your words), then installs the declared tools the plan showed as missing or wrong: go install NAME@VERSION for a go tool, and for a binary the file at its URL, downloaded to a temporary name, kept only when its sha256 is the declared one, made executable and moved to ~/.local/bin/NAME (a failed tool is named, the others still run, exit 1). It records the run in ~/.qargi/state/env/NAME.json (mode 600) and then runs qargi env check (the project's doctor), whose verdict ends the output and whose exit status is the verb's. QARGI_DRY_RUN stops it after the checks, before the bootstrap runs. A member's guard refuses it.

qargi env apply --plan 0123456789ab --approved "install the tools" --approve-exec make,go
qargi env apply --plan 0123456789ab --approved "go" --approve-exec make,pacman --allow-root

qargi instances #

Register, inspect and manage agent instances.

An instance is <project>-<role>, for example acme-build, or the lead acme-lead. The registry records where it runs and which resources it uses. Verbs that change cloud resources need --asked, and show a plan first.

qargi instances init #

qargi instances init [OPTIONS]

Register an instance.

Usually you provision (qargi provision) and the instance is registered for you.

qargi instances init --location local --agent ./agent.md --name acme-build

qargi instances list #

qargi instances list [OPTIONS]

List the instances (cloud ones whose prompt is out of date are marked STALE) and their active sessions.

qargi instances show #

qargi instances show NAME [OPTIONS]

Show an instance and what is stale or misnamed.

qargi instances remove #

qargi instances remove NAME

Forget an instance (the registry entry only).

Refused while it has open sessions.

qargi instances budget #

qargi instances budget NAME CENTS [OPTIONS]

Change the spend ceiling of the instance's deployment.

qargi instances refresh-prompt #

qargi instances refresh-prompt NAME [OPTIONS]

Rebuild the agent's system prompt from the current contract.

Prints what changes, then creates a new agent version and re-points the deployment. The hash of the prompt (and of the skill in it) is recorded when an agent is provisioned or refreshed; instances list marks a changed one with STALE and instances show says which part changed. An instance with no recorded hash is unknown, not stale.

qargi instances normalize #

qargi instances normalize NAME [OPTIONS]

Rename the instance's cloud resources to the naming convention.

qargi skill #

Create or import skills and attach them by scope.

Skills and tools share one library with globally unique names; a link attaches one at a scope: user (every project and role), user-role, project, or project-role. Imported content is shown, hashed and approved before it is stored, and any later change is drift until you seal it again. Only you, with the person present, change a skill: a local member's guard refuses the verbs new, import, seal, remove, link, unlink, accept, unaccept, enable and disable, and writes in the pack library, and QARGI_NESTED does not stand in for the plan token of import and seal.

qargi skill new #

qargi skill new NAME [OPTIONS]

Create a pack from a template.

qargi skill import #

qargi skill import SOURCE [OPTIONS]

Import a pack from a directory, file or pinned git URL, after a review (a top-level .pack.json in the source is qargi's own record: ignored, not copied).

qargi skill list #

qargi skill list [PROJECT] [ROLE]

List the library, or what a project and role get.

qargi skill show #

qargi skill show NAME

Show a pack.

qargi skill seal #

qargi skill seal NAME [OPTIONS]

Approve the current content of a pack (after you edited it).

A pack with no compatible_providers needs --compatible once; giving it again changes the declaration and the plan says so.

qargi skill link #

qargi skill link NAME [OPTIONS]

Attach a pack at a scope.

qargi skill unlink #

qargi skill unlink NAME [OPTIONS]

Detach a pack from a scope (same options as link).

qargi skill enable #

qargi skill enable [PROJECT] ROLE NAME

Re-enable a pack for a role that opted out.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi skill disable #

qargi skill disable [PROJECT] ROLE NAME

Opt a role out of a pack.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi skill effective #

qargi skill effective [PROJECT] ROLE

List what a role gets.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi skill check #

qargi skill check [PROJECT] ROLE

Review, drift and missing packs of a role.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi skill remove #

qargi skill remove NAME

Delete a pack.

Refused while it is linked.

qargi skill accept #

qargi skill accept [PROJECT] NAME [OPTIONS]

Accept a skill a session loads that qargi does not manage.

Finds NAME among the skills a session opened in the project's checkout would load (the checkout, the render and the user's skills directory; see qargi packs check) and applies only to one that is unmanaged or drifted. Without --plan it prints the same review as skill import (files, scripts, URLs, network commands, secret findings) and a plan token that covers the scope, the name and the content hash. With --plan and --approved it records the name, the content hash, the path and your words in the acceptances file, for this project or, with --user, for every project, and writes an audit line. An accepted skill shows as accepted in packs check; if its content changes it shows as drifted and packs check exits 1. qargi skills, excluded skills and skills already accepted are refused with the reason. A local member's guard refuses it.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi skill unaccept #

qargi skill unaccept [PROJECT] NAME [OPTIONS]

Remove the acceptance of a skill.

Gated like accept. Removes only the record: the skill itself is not touched and shows as unmanaged again. Refused when there is no such acceptance in that scope.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi tool #

Create or import tools (MCP servers with an allowlist) and attach them by scope.

A tool is an MCP server with an explicit list of allowed tools and a permission policy for each. A write-like tool cannot run unattended unless the tool is marked write_ok. Everything else works as for skills (qargi help skill).

qargi tool new #

qargi tool new NAME [OPTIONS]

Create a pack from a template.

qargi tool import #

qargi tool import SOURCE [OPTIONS]

Import a pack from a directory, file or pinned git URL, after a review (a top-level .pack.json in the source is qargi's own record: ignored, not copied).

qargi tool list #

qargi tool list [PROJECT] [ROLE]

List the library, or what a project and role get.

qargi tool show #

qargi tool show NAME

Show a pack.

qargi tool seal #

qargi tool seal NAME [OPTIONS]

Approve the current content of a pack (after you edited it).

A pack with no compatible_providers needs --compatible once; giving it again changes the declaration and the plan says so.

qargi tool link #

qargi tool link NAME [OPTIONS]

Attach a pack at a scope.

qargi tool unlink #

qargi tool unlink NAME [OPTIONS]

Detach a pack from a scope (same options as link).

qargi tool enable #

qargi tool enable [PROJECT] ROLE NAME

Re-enable a pack for a role that opted out.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi tool disable #

qargi tool disable [PROJECT] ROLE NAME

Opt a role out of a pack.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi tool effective #

qargi tool effective [PROJECT] ROLE

List what a role gets.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi tool check #

qargi tool check [PROJECT] ROLE

Review, drift and missing packs of a role.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi tool remove #

qargi tool remove NAME

Delete a pack.

Refused while it is linked.

qargi packs #

Render, load or apply the skills and tools a role gets.

qargi packs render #

qargi packs render [PROJECT] ROLE OUTDIR

Write what a role gets into a directory (used by provisioning).

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi packs load #

qargi packs load [PACK] [OPTIONS]

Show what a role has enabled, or print one pack's text.

Read-only, and evaluated from the links when called, so enabling or disabling a pack takes effect at once. Refuses a pack that fails its review or changed since it was approved.

qargi packs apply #

qargi packs apply INSTANCE|PROJECT [OPTIONS]

Update an existing cloud agent, or render for a local runtime.

Without --target (or with managed-agents) this updates the existing cloud agent INSTANCE with its skills and tools; the lead's GitHub tool arrives this way when the project grants a cloud push. It needs --asked, and always needs --plan (QARGI_NESTED does not skip it); a local member's guard refuses it. With --target claude-code it takes PROJECT instead of INSTANCE and needs no --asked. Without --approved it prints a plan token. With --plan and --approved it renders the project's enabled skills and tools into $QARGI_STATE/render/PROJECT/RUNTIME (claude-code for this target), replacing the previous render atomically, and prints the exact `claude --add-dir ...` launch line (with --mcp-config and --settings when the render has them). A local runtime cannot enforce role scoping, so the render is the union of the project's roles and role scoping is advisory there. Skills render under .claude/skills; tool packs render mcp.json and settings.json. Nothing is written into a repository or into ~/.claude, and members cannot write under the state's render/ directory. The plan refuses, naming the pack and writing nothing, a skill whose SKILL.md name differs from the pack name, whose front matter is not closed or has more than one name key; a skill and a tool with the same name; and a tool allowlist name outside letters, digits, _, . and -. Each plan stages into its own hidden directory and a lock serializes concurrent applies; the second refuses if the render changed meanwhile. The swap installs only the tree the token approved; the token also covers the file modes, which the manifest records.

qargi packs seed #

qargi packs seed [OPTIONS]

Add or update the baseline packs shipped with qargi in your library.

qargi ships a few packs (packs/ in its tree). Seeding stores them in your library. Without --approved it prints one line per pack (add, update, current or kept) and a plan token. A pack you edited and sealed, or one of your own with the same name, is kept and never overwritten; an untouched shipped copy is updated when qargi ships a newer text. Seeding never links a pack: nothing reaches a project or an agent until you link it.

qargi packs check #

qargi packs check [PROJECT] [OPTIONS]

Check a render for drift (read only).

Needs --target claude-code. Writes nothing and exits 1 on any finding: library drift (a pack changed or failed review since it was rendered), rendered tampering (a file differs from the manifest, or an extra or missing file), enablement drift (a pack enabled or disabled, or its roles changed, since the render), shadowing of a rendered skill by ~/.claude/skills or by the checkout's .claude/skills, and a render directory that has no manifest (a broken render). A project with no render at all is not a failure: the check prints a not applied line with the command that applies it and exits 0. The answer packs.none: true says the project uses no project packs; the check then passes with no render, and fails if a pack is linked to a role of the project. It also reports a rendered file that differs from the library copy (even when the manifest was edited with it), a changed file mode, a group- or world-writable render, a malformed manifest, and a manifest that names another project or whose role scoping is not advisory. It ends with a section, skills a session would load, that gives every skill a session opened in the checkout would load one state: qargi (a library pack with approved content, or a skill shipped with qargi), accepted (skill accept), drifted (accepted, but its content changed: this exits 1), excluded (switched off in the provider's settings; qargi only reads them) or unmanaged (everything else, shown with what to do about it; this does not change the exit status). When the checkout's skills directory is not linked to the render it adds a note naming packs link.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi packs link #

qargi packs link [PROJECT] [OPTIONS]

Make the project's checkout load its packs by itself.

The provider's project skills directory in the repository (for Claude Code .claude/skills) becomes a symbolic link to the render made by packs apply --target. Without --approved it prints the plan, the skills a session would load, and a plan token; apply with --plan TOKEN --approved. If the directory is absent it creates the link; if it is already that link it says so and exits 0. It refuses a link to anywhere else, a symlinked parent, a checkout that is not the top of a git work tree, a missing render, and files tracked by git. If it is a real directory the plan lists each skill in it as same, differs or new against the library and offers skill import and skill link for the new ones; apply then moves the directory to the backup name (skills.qargi-backup beside it) and links, so skills not imported stop loading until they are. Nothing is deleted. If git does not ignore the path it prints the line to add to .git/info/exclude and never edits that file. A provider that has no such directory is refused (exit 3). Every verb that takes --target (packs apply, packs check), packs link and unlink, skill accept and marshal handoff exit 2 when the project has no provider (qargi project set P models.provider NAME). A local member's guard refuses it.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi packs unlink #

qargi packs unlink [PROJECT] [OPTIONS]

Undo packs link.

Removes only the symbolic link that points to this project's render and, if the backup exists, moves it back to the skills directory. Refuses a link to anywhere else, a real directory in its place, and a backup with no link of ours. Same plan token and approval as link; nothing else is deleted.

PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.

qargi discover #

Find, recommend and install tools for the roles of a project.

A tool is a skill, an MCP server, a package for the sandbox or a built-in tool of the agent. search looks in the reviewed catalog and your library and, with --online, in the official MCP registry and Anthropic's skills. recommend ranks the catalog for each role of a project by the stack it sees in the repository, leaving out what the role has. install asks which scope the tool should reach (user, user-role, project, project-role), then goes through the existing gates: a skill or an MCP server is imported with its review and your approval of exactly that content, linked at the scope, and offered to the cloud agents it reaches with the plan shown first. Nothing found online is installed on trust. install changes skills, so a local member's guard refuses it.

qargi discover sources #

qargi discover sources

List what is searched.

qargi discover search #

qargi discover search QUERY [OPTIONS]

Search the catalog, your library and, with --online, the registries.

qargi discover search pdf
qargi discover search github --online --kind mcp

qargi discover recommend #

qargi discover recommend [PROJECT] [OPTIONS]

Rank the catalog for the roles of a project.

qargi discover recommend acme --role build

qargi discover show #

qargi discover show ID

Show one entry: what it is, its risk and how it installs.

qargi discover install #

qargi discover install ID [OPTIONS]

Install an entry: review, approval, scope, link.

Interactive: it asks at the terminal, and your answers are the recorded approvals.

qargi discover install skill-pdf --project acme --role write