{"_id":"@anmol098/agentchat","_rev":"3-59f87a349c35ce1fd043108621dce519","name":"@anmol098/agentchat","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@anmol098/agentchat","version":"0.2.0","license":"MIT","_id":"@anmol098/agentchat@0.2.0","maintainers":[{"name":"anmol098","email":"anmolpratapsingh1997@gmail.com"}],"homepage":"https://github.com/anmol098/agentchat/tree/main/packages/cli#readme","bugs":{"url":"https://github.com/anmol098/agentchat/issues"},"bin":{"agentchat":"dist/bin.js"},"dist":{"shasum":"7ec74f1520119520918aaa23a3a6378ff0819a55","tarball":"https://registry.npmjs.org/@anmol098/agentchat/-/agentchat-0.2.0.tgz","fileCount":143,"integrity":"sha512-QhxtCp8YMPbFbLwWSmYLPu0sYiv4BPYOiLPobyQRXlpuFtmRrlehcqO0MrLTtPohp58/scV0Nn1nj3d9NxVr5Q==","signatures":[{"sig":"MEYCIQCnsa1X47YMOOxU47s1lRrA+uRxS+AMJKlPvK03UeeREwIhAL6s31G/6bY+jdQ/avII8yN9ApDEd36rFTxpL1lh63kp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anmol098%2fagentchat@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1114867},"main":"./dist/index.js","type":"module","_from":"file:/home/runner/work/_temp/pack/cli/anmol098-agentchat-0.2.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc -b tsconfig.json && chmod +x dist/bin.js","clean":"rm -rf dist tsconfig.tsbuildinfo","typecheck":"tsc -b tsconfig.json && tsc -p tsconfig.test.json"},"_npmUser":{"name":"anmol098","email":"anmolpratapsingh1997@gmail.com"},"_resolved":"/home/runner/work/_temp/pack/cli/anmol098-agentchat-0.2.0.tgz","_integrity":"sha512-QhxtCp8YMPbFbLwWSmYLPu0sYiv4BPYOiLPobyQRXlpuFtmRrlehcqO0MrLTtPohp58/scV0Nn1nj3d9NxVr5Q==","repository":{"url":"git+https://github.com/anmol098/agentchat.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.19.0","description":"The `agentchat` command-line interface: the command framework, output modes, and exit-code contract.","directories":{},"_nodeVersion":"24.20.0","dependencies":{"@stackgrid/client":"0.2.0","@stackgrid/protocol":"0.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"24.10.1"},"_npmOperationalInternal":{"tmp":"tmp/agentchat_0.2.0_1789014857449_0.654358699678885","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@anmol098/agentchat","version":"0.2.1","license":"MIT","_id":"@anmol098/agentchat@0.2.1","maintainers":[{"name":"anmol098","email":"anmolpratapsingh1997@gmail.com"}],"homepage":"https://github.com/anmol098/agentchat/tree/main/packages/cli#readme","bugs":{"url":"https://github.com/anmol098/agentchat/issues"},"bin":{"agentchat":"dist/bin.js"},"dist":{"shasum":"d4e7decefad2a01dc697d7780d2211596af51aed","tarball":"https://registry.npmjs.org/@anmol098/agentchat/-/agentchat-0.2.1.tgz","fileCount":143,"integrity":"sha512-bt795TcknIaEcZXE0JvQNCI+fGMXSlyyIEhY4kO5OapPxFhECzMKlm3cJdN02tiCv6VzzROcFsyyp71a3BUXNQ==","signatures":[{"sig":"MEYCIQCb19sfm62iNpmFLfurkZx7FJj/nG+otyZCzzfCHcUbEgIhAN1VsMASKx+h4QDE0XseaOptzbR9fff8eE2QB8xw7YL/","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIHBtU/xUQxcR/NdR+i0WxJVfawEoxECdPhZGCUdffQ/NAiEAxDPnpBHFp7PoaKjvNDPE6d2Gz+3wJK2WMP8Bv0MPu68=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anmol098%2fagentchat@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1114963},"main":"./dist/index.js","type":"module","_from":"file:/home/runner/work/_temp/pack/cli/anmol098-agentchat-0.2.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc -b tsconfig.json && chmod +x dist/bin.js","clean":"rm -rf dist tsconfig.tsbuildinfo","typecheck":"tsc -b tsconfig.json && tsc -p tsconfig.test.json"},"_npmUser":{"name":"anmol098","email":"anmolpratapsingh1997@gmail.com"},"_resolved":"/home/runner/work/_temp/pack/cli/anmol098-agentchat-0.2.1.tgz","_integrity":"sha512-bt795TcknIaEcZXE0JvQNCI+fGMXSlyyIEhY4kO5OapPxFhECzMKlm3cJdN02tiCv6VzzROcFsyyp71a3BUXNQ==","repository":{"url":"git+https://github.com/anmol098/agentchat.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.19.0","description":"The `agentchat` command-line interface: the command framework, output modes, and exit-code contract.","directories":{},"_nodeVersion":"24.20.0","dependencies":{"@stackgrid/client":"0.2.1","@stackgrid/protocol":"0.2.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"24.10.1"},"_npmOperationalInternal":{"tmp":"tmp/agentchat_0.2.1_1789192559452_0.9569973734226112","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"@anmol098/agentchat@0.3.0","bin":{"agentchat":"dist/bin.js"},"bugs":{"url":"https://github.com/anmol098/agentchat/issues"},"dist":{"shasum":"c1997e787b92cbf6acda048f6fd1f29b4242420d","tarball":"https://registry.npmjs.org/@anmol098/agentchat/-/agentchat-0.3.0.tgz","fileCount":144,"integrity":"sha512-Fyy2/UfUpXg6INJH7UblqvwwPbJtMBhLrUZoKoPkIJfTEQDq44NXtFVzGak4GV413T+iZgaEbsNDVW36zt0DYA==","signatures":[{"sig":"MEUCIFNwQOSB1E3PfuuI9Tm/4CYgtT5ukXlzfO4uiGHBce5AAiEAoPXTWKiBq9HOTZ/oinTFxO0dpy0fpTyBiDLp5qdaqbk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD+oAjWIYvmqEkpx3v3a02Nhuq+2oTpl+q0ewIHSQGMXgIhAJ48+deZtgEnH5Zt1uTxM8v+NC3e3nKNR1cNEhxbG4ks"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anmol098%2fagentchat@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1118817},"main":"./dist/index.js","name":"@anmol098/agentchat","type":"module","_from":"file:/home/runner/work/_temp/pack/cli/anmol098-agentchat-0.3.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"license":"MIT","scripts":{"build":"tsc -b tsconfig.json && chmod +x dist/bin.js","clean":"rm -rf dist tsconfig.tsbuildinfo","typecheck":"tsc -b tsconfig.json && tsc -p tsconfig.test.json","postinstall":"[ -f scripts/postinstall-skill.mjs ] && node scripts/postinstall-skill.mjs; exit 0"},"version":"0.3.0","_npmUser":{"name":"anmol098","email":"anmolpratapsingh1997@gmail.com"},"homepage":"https://github.com/anmol098/agentchat/tree/main/packages/cli#readme","_resolved":"/home/runner/work/_temp/pack/cli/anmol098-agentchat-0.3.0.tgz","_integrity":"sha512-Fyy2/UfUpXg6INJH7UblqvwwPbJtMBhLrUZoKoPkIJfTEQDq44NXtFVzGak4GV413T+iZgaEbsNDVW36zt0DYA==","repository":{"url":"git+https://github.com/anmol098/agentchat.git","type":"git","directory":"packages/cli"},"_npmVersion":"11.19.0","description":"The `agentchat` command-line interface: the command framework, output modes, and exit-code contract.","directories":{},"maintainers":[{"name":"anmol098","email":"anmolpratapsingh1997@gmail.com"}],"_nodeVersion":"24.20.0","dependencies":{"@stackgrid/client":"0.3.0","@stackgrid/protocol":"0.3.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"24.10.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentchat_0.3.0_1789283718969_0.7311511450473704"}}},"time":{"created":"2026-09-10T04:34:17.274Z","modified":"2026-09-13T07:15:19.421Z","0.2.0":"2026-09-10T04:34:17.586Z","0.2.1":"2026-09-12T05:55:59.547Z","0.3.0":"2026-09-13T07:15:19.071Z"},"bugs":{"url":"https://github.com/anmol098/agentchat/issues"},"license":"MIT","homepage":"https://github.com/anmol098/agentchat/tree/main/packages/cli#readme","repository":{"url":"git+https://github.com/anmol098/agentchat.git","type":"git","directory":"packages/cli"},"description":"The `agentchat` command-line interface: the command framework, output modes, and exit-code contract.","maintainers":[{"name":"anmol098","email":"anmolpratapsingh1997@gmail.com"}],"readme":"# `agentchat`\n\nThe `agentchat` command-line interface: the command framework, the two output\nmodes, and the exit-code contract every command inherits.\n\nMIT, like everything under `packages/`. It depends on `@stackgrid/client` and\n`@stackgrid/protocol` and on nothing under `server/`.\n\n```bash\nnpm install --global @anmol098/agentchat\nagentchat --help\n```\n\nThe package is scoped and the command it installs is `agentchat`: npm refused\nthe unscoped name as too similar to an existing package, and `bin` names the\ncommand independently of the package. Its two dependencies are published\nalongside it at the same version rather than bundled into this tarball, because\n`packages/` is permissive so that third parties can embed the protocol, and a\nbundled copy is not something anyone can import.\n\n## The contract\n\n> `stdout` carries machine-consumable output only. Every operational log, every\n> progress message, every warning goes to `stderr`.\n\nAn AI coding agent reads this process's stdout to consume messages. One stray log\nline there corrupts its input, and the failure is silent on our side and\nbaffling on theirs. So the rule is enforced by the types rather than by review: a\ncommand is handed a `CommandContext`, and there is no writable stdout anywhere in\nit.\n\n```text\n             ┌─────────────────────────────┐\n  argv  ───▶ │ run()                       │\n             │  scan mode ─▶ resolve ─▶ …  │\n             └──────┬───────────────┬──────┘\n                    │               │\n              context.emit    context.log\n                    │               │\n                    ▼               ▼\n                 stdout          stderr\n             results only    everything else\n```\n\n## Output modes\n\nEvery command accepts `--json`, whether or not it has a machine-readable result.\nA harness that appends the flag to whatever the user typed cannot know which\ncommands opted in, so all of them do.\n\n| Mode     | stdout                          | stderr                       |\n| -------- | ------------------------------- | ---------------------------- |\n| human    | the rendered result             | logs, warnings, errors, help |\n| `--json` | newline-delimited JSON, or none | logs and warnings only       |\n\nIn `--json` mode, one `emit` is one line and one complete JSON value — never\npretty-printed, never coloured, whatever the environment or the flags say. Most\ncommands emit once, so their stdout is a single JSON document; `listen` emits per\nevent, as a newline-delimited JSON stream. A consumer parses line by\nline without needing to know which kind of command it ran.\n\n### A failure is machine-readable too\n\n```console\n$ agentchat --json project current\n{\"error\":{\"code\":\"NO_PROJECT\",\"message\":\"No project is configured for this directory.\",\"hint\":\"Run `agentchat project init <slug>` in this repository, or pass --project.\"}}\n$ echo $?\n4\n```\n\n`error.code` and `error.message` are exactly `ErrorEnvelopeSchema` from\n`@stackgrid/protocol` — the same envelope the server sends over HTTP and over the\nWebSocket — so a harness needs one error handler and not two. `hint` is the one\naddition and is additive: a consumer that ignores it is unaffected.\n\n`code` is the code **as it arrived on the wire**, which may be one this build has\nnever heard of. The exit code is derived from a code this build does know.\n\nThe envelope is not duplicated onto stderr. A harness that merges the two\ndescriptors would otherwise see every failure twice.\n\nIn human mode the reverse holds: the error is rendered on stderr and **stdout\nstays completely empty**.\n\n```console\n$ agentchat project current\nerror: No project is configured for this directory.\n  code: NO_PROJECT\n  next: Run `agentchat project init <slug>` in this repository, or pass --project.\n```\n\nA stack trace is never printed. `--verbose` adds the chain of `cause` messages on\nstderr, which is what actually says where a failure came from.\n\n## Exit codes\n\n| Code | Meaning                    | What a harness should do             |\n| ---- | -------------------------- | ------------------------------------ |\n| 0    | success                    | continue                             |\n| 1    | generic failure            | may retry                            |\n| 2    | usage error                | fix the invocation; do not retry     |\n| 3    | authentication required    | run `agentchat login`, then retry    |\n| 4    | no project or agent context| write a project config, then retry   |\n\nEach code above 1 exists because it has a *different remedy that can be\nautomated*. That is the test a new exit code has to pass, and it is why so many\nerror codes map to 1.\n\n## Global options\n\n| Flag                     | Effect                                                    |\n| ------------------------ | --------------------------------------------------------- |\n| `--json`                 | machine-readable stdout, including on failure              |\n| `--server <url>`         | the server to talk to; also `AGENTCHAT_SERVER`             |\n| `--color` / `--no-color` | force decoration on or off                                 |\n| `--quiet`                | suppress progress and warnings on stderr                   |\n| `--verbose`              | report causes and detail on stderr                         |\n| `-h`, `--help`           | show help; goes to **stdout**, because you asked for it    |\n| `--version`              | print the version                                          |\n\n### Colour\n\nOff unless the stream being written to is a terminal, decided **per descriptor**\n— `agentchat status | less` still has a human watching stderr. Overrides, in\norder: `--color`/`--no-color`, then `NO_COLOR`, then `FORCE_COLOR`, then\n`TERM=dumb`. JSON output is never coloured under any of them.\n\n## Adding a command\n\n```ts\nimport type { Command } from 'agentchat';\nimport { view } from 'agentchat';\n\nexport const whoamiCommand: Command = {\n  kind: 'command',\n  name: 'whoami',\n  summary: 'show the signed-in account',\n  async run(context) {\n    context.log.info('Checking credentials…'); // stderr, in both modes\n    const client = buildClient(context); // see src/commands/version.ts\n    const me = await client.auth.me({ signal: context.signal });\n    await context.emit(\n      view({ handle: me.handle }, (writer) => {\n        writer.fields([['handle', me.handle]]);\n      }),\n    );\n  },\n};\n```\n\nConstructing the client is still each command's own business: it needs a\n`CredentialStore`, and the file-backed one lives in `src/credentials.ts`. A\nnatural next step is to build the client once in `run()` and hand it to the\ncontext, so that `--server` resolution and the credential store are settled in\none place rather than in each command.\n\nThen add it to `src/commands/index.ts`. It inherits every global option, colour\nthat disappears when piped, the error renderer, and an exit code without doing\nanything.\n\nTo fail, **throw**. `CliError` carries a stable code and the next step;\n`UsageError` is the one for a bad invocation. Anything `@stackgrid/client` raises\nis already a `ProtocolError` and needs no translation. A command never writes an\nerror and never picks an exit code.\n\nDeclare `positionals: { min, max }` if the command takes arguments. The default\nis none, and the framework rejects the wrong number before `run` is called, so\nevery command reports the same mistake the same way.\n\n## Testing\n\nTwo levels, and both matter.\n\n`src/**/*.test.ts` drive `run()` in process against fake descriptors, via\n`captureRun` from `src/testing.ts`. Fast, and the right place for a branch.\n\n`tests/*.test.ts` **spawn a real process** and read file descriptors 1 and 2\nseparately. That is the level at which the stdout contract is actually provable:\na formatter test cannot catch a `console.log` left in a command, a library that\nwarns on stdout, or a build that prints a banner, and every one of those silently\ncorrupts a harness's input.\n\n```bash\npnpm --filter agentchat build   # tests build automatically, but this is the binary\nnode packages/cli/dist/bin.js version --json\n```\n\n## Argument parsing\n\n`node:util`'s `parseArgs`, and no dependency. Subcommand resolution, help, and\nusage errors are this package's own because they have to match its conventions\nanyway; a parser library would have supplied the easy half. See the module\ncomment in `src/args.ts` for why `commander` and `yargs` were both declined.\n","readmeFilename":"README.md"}