Agnostic CLI

Data reads (introduced in 0.6.0)

Use agnostic data login --access schema for schema-only access or --access records for explicitly authorized records. Existing grants do not expand. agnostic data schema --project <id> --environment <id> --out schema.json --json creates a complete, private, new snapshot. data records and data count take a collection ID; data aggregate also takes --input aggregate.json. Query files cannot override scope. Publishing this package version is a separate action.

Managed Data workflows (0.7.0 release candidate)

Admin/developer Local Agent profiles can use the fixed managed workflow; Data read and workspace credentials are never substituted:

agnostic data plan --project <id> --input desired-schema.json --json
agnostic data plan-status <plan-id> --project <id> --json
agnostic data prepare <plan-id> --hash <sha256:...> --project <id> --json
agnostic data job status <job-id> --project <id> --json
agnostic data job wait <job-id> --timeout 600 --project <id> --json
agnostic data job logs <job-id> --after 0 --limit 100 --project <id> --json
agnostic data job report <job-id> --project <id> --json

Plan creation persists an immutable preview only. Prepare verifies the exact plan/hash and returns a browser confirmation URL; CLI has no confirm or cancel command. Job pages are bounded to 200 safe events. Wait timeout/cancellation detaches only the local observer, while a terminal report verifies one stable snapshot across all event pages.

Data import validation

An admin/developer Local Agent profile can upload one explicit regular JSONL.gz file to a private scoped artifact and validate it without writing records:

agnostic data import validate ./records.jsonl.gz --project <id> --environment <id> --collection <id> --json

The CLI refuses symbolic links and files over 100 MiB, hashes and uploads the same open file, sends no bearer token to the signed upload URL, and never prints that URL. The result contains only the artifact status, counters and safe error summary. After validation, create and inspect an immutable insert-only plan, then hand its exact hash to the browser confirmation screen:

agnostic data import plan <artifact-id> --project <id> --json
agnostic data import plan-status <plan-id> --project <id> --json
agnostic data import plan-links <plan-id> --after 0 --limit 100 --project <id> --json
agnostic data import prepare <plan-id> --hash <sha256:...> --project <id> --json
agnostic data job wait <job-id> --project <id> --json
agnostic data import job-links <job-id> --after 0 --limit 100 --project <id> --json

The browser shows the exact destination, row/chunk/link counts, checks and policy. CLI never confirms or cancels the action. Records are written first; explicit links are restored only after record verification. Missing, ambiguous, cross-environment and unsupported required links block strict plans. Closing the browser or interrupting wait only detaches the observer.

Official CLI package for backend-mediated local workspace development.

npm install -g @nsp-labs/agnostic-cli

agnostic login
agnostic workspace clone <project-id> ./api --unit api
agnostic workspace status
agnostic workspace pull
agnostic workspace push -m "feat: update API" --build --json
agnostic build status <build-id> --json
agnostic build wait <build-id> --timeout 600 --json

Local Agent API commands use the same API origin and user-level credential store:

agnostic agent setup codex --environment <environment-id>
agnostic agent doctor codex
agnostic context sync --project <project-id> --environment <environment-id>
agnostic agent context --json
agnostic agent capabilities --json
agnostic agent prepare app.auth.configure --input ./action.json --json
agnostic agent status <action-id> --json
agnostic agent wait <action-id> --json

Replace codex with claude or cursor for another supported client. agent setup authorizes the server-managed local-agent profile, performs the first context sync, and registers the absolute agnostic-mcp command in the client's user-level configuration. It never writes a bearer token into an MCP configuration. --dry-run reports required work without opening a browser or writing files; repeating setup is idempotent. agent doctor is read-only.

Generated context reads the installed Runtime SDK manifest. For Files it lists the exact storage.bucket(name) lifecycle methods and reminds agents that the SDK/runtime token stay in backend code while only short scoped URLs may cross into a browser.

The first sync needs a project/environment selection. Later commands resolve it from --project/--environment, AGNOSTIC_PROJECT_ID / AGNOSTIC_ENVIRONMENT_ID, .agnostic/agent-context.json, and existing workspace metadata in that order. context sync refreshes the generated machine-readable cache and its deterministic Markdown projection:

.agnostic/
├── agent-context.json
└── context/
    ├── AGENT_CONTEXT.md
    └── resources/
        ├── data/<slug>.md
        ├── workflows/<slug>.md
        ├── app-auth.md
        └── connections/<slug>.md

Read AGENT_CONTEXT.md first, then the relevant resource card. Cards contain safe current state plus Data CRUD, Workflow start/wait, App Auth session, and protected Connection handoff recipes. Available SDK methods are taken from the installed @nsp-labs/agnostic-sdk manifest.

All Agent commands accept --json, --quiet, and --non-interactive. --json writes one versioned JSON object. --quiet writes nothing on success; errors still go to stderr. --non-interactive guarantees that the command does not open a browser or prompt, while agent prepare still returns the browser confirmation URL.

agent wait returns:

| Exit | Meaning | | ---: | --------------------------------- | | 0 | Action succeeded | | 3 | Rejected | | 4 | Confirmation expired | | 5 | Cancelled | | 6 | Confirmed execution failed | | 7 | Wait timeout | | 8 | Context is stale | | 9 | CLI/API versions are incompatible |

Invalid CLI input, including credential-like Agent payload fields, uses exit code 2; other authentication/API failures use 1. JSON errors use agnostic_cli_error.v1.

workspace clone writes the selected service/site files directly into the destination folder. The CLI stores a non-secret path mapping in .agnostic/workspace.json, so workspace push can be run from that folder without repeating project or unit flags.

workspace push --build sends only the bounded workspace diff and starts a build for the exact commit created by that push. Its JSON result contains the commit and safe build id; build status reads the current exact status, while build wait polls the same read-only route with backoff until success or failed. The wait timeout defaults to 10 minutes and cannot exceed one hour; timeout uses exit code 7, and cancellation uses 5. Both commands return a sanitized, bounded log excerpt without provider references. A successful build never starts deploy. Local agents prepare app.deploy separately with the exact unit, build, commit, and selected environment, then wait for browser confirmation and verified health/public URL.

agnostic login uses https://api.agn0.ru/ by default. Pass --api-url only when targeting a local or custom API, for example agnostic login --api-url http://localhost:3000/api. Browser login always requests the server-defined workspace profile. The CLI does not accept arbitrary scope flags; Local Agent authorization uses a separate server-managed profile in the agent setup flow. Workspace and Local Agent credentials are stored separately in the same ~/.agnostic/config.json file so MCP never needs a copied secret. Repeating agnostic login for the same API validates and reuses an active saved token without opening the browser or issuing another token. Use agnostic login --force only to switch accounts or replace a token deliberately.

The local .agnostic/workspace.json stores only workspace metadata. API access tokens and backend workspace tokens are stored in the user's home directory under ~/.agnostic.

.agnostic/agent-context.json and .agnostic/context/** are disposable server projections. They contain safe logical resource state and no API token, provider credential, runtime token, encrypted secret payload, or reusable secret reference. Context sync atomically replaces the complete projection, uses owner-only permissions, and preserves the previous complete projection when rendering or writing fails. The whole .agnostic/** tree is ignored by workspace diff/push.