The Anima CLI

The Anima CLI is a command-line interface: a tool that coding and autonomous agents use by typing commands in a terminal. Version 0.9 can list reachable workspaces, meaning workspaces the agent can access. It can also create or duplicate into a chosen workspace, edit and review artifacts, and publish when you explicitly request it.

1. Run the CLI

No global install is required:

npx @animaapp/cli@latest --help

The package is called @animaapp/cli because Anima and AgentGrid.io share infrastructure.

2. Log in

npx @animaapp/cli@latest login

The CLI prints a verification URL and short code. Open the URL on any device and approve the agent. Never paste your password or a stored credential into the agent's chat.

A pre-authorized agent can instead redeem a one-time invite:

npx @animaapp/cli@latest login --invite <invite-url-or-code>

3. Verify identity and access

npx @animaapp/cli@latest workspaces

A successful response lists the workspaces the agent can read and its capabilities in each. A capability is permission to perform an action such as read, write, share, or publish. This is a better connection check than expecting a particular artifact to exist.

A team ID uniquely identifies a team. A workspace ID uniquely identifies a workspace. An artifact session ID uniquely identifies an artifact. Commands that accept --workspace require the workspace ID returned by workspaces; artifact commands accept an artifact URL or session ID.

4. List workspaces

npx @animaapp/cli@latest workspaces

The result includes only workspaces reachable by this agent. Copy the intended workspace ID for later commands. Workspace access is separate from team membership and from the agent's capabilities. See Workspace access.

5. List artifacts

npx @animaapp/cli@latest list
npx @animaapp/cli@latest list --workspace <workspace-id>

Without --workspace, list spans every workspace the agent can read. With it, the result is filtered to one workspace. Results are ordered by most recent update.

6. Create or import

An empty app repository:

npx @animaapp/cli@latest create -t empty --framework react --workspace <workspace-id>

Import a folder or .zip as the first commit:

npx @animaapp/cli@latest create -t import --from ./project --artifact-type app --workspace <workspace-id>

Use --artifact-type markdown for a document. Apps need an entry point; Markdown imports need .md files. The CLI also supports generated p2c, l2c, and f2c creates; run create --help for their required inputs.

--workspace is optional only when the agent can create in exactly one workspace. When it can create in several, there is no default and the workspace ID is required.

After creation, open the returned artifactUrl, or run list --workspace <workspace-id> and confirm the new session ID.

For a server-template knowledge artifact, use:

npx @animaapp/cli@latest create-knowledge --workspace <workspace-id>

7. Duplicate

npx @animaapp/cli@latest duplicate <artifact-url-or-session-id> --workspace <workspace-id>

The destination requires create access; the source requires read access. The copy is independent and includes code, assets, and supported database content, but not chat or custom domains.

Running the duplication command twice can create two copies. If the command times out or its response is lost, list recent artifacts in the destination workspace before retrying; the copy may already exist.

8. Explore and edit

Use explore to inspect files and history and edit to commit a change without a local clone:

npx @animaapp/cli@latest explore <artifact-url-or-session-id>
npx @animaapp/cli@latest edit <artifact-url-or-session-id> --help

For a real checkout, mint a short-lived remote with get-git-token. Read the current state before editing and verify the resulting revision afterwards.

9. Review

npx @animaapp/cli@latest review list
npx @animaapp/cli@latest review reply <comment-id> --help
npx @animaapp/cli@latest review resolve <comment-id>

list reads review comments addressed to the agent. reply answers while leaving a comment open; resolve closes it. See Review and comments.

10. Publish

Only publish after an explicit human request and only with the publish capability:

npx @animaapp/cli@latest publish <session-id>
npx @animaapp/cli@latest unpublish <session-id>

Publishing creates or updates a public site; it is not the same as sharing an artifact link. Verify the returned public URL. See Publish to a public URL.

11. Errors and retry rules

• Workspace is absent from workspaces: this is a terminal failure for the current grant. Retrying cannot help until a human grants access. Do not probe for private workspace or artifact details.
• Missing capability: this is a terminal failure until a human changes access. Relay the denied operation.
• Artifact capacity or URL/Figma import allowance reached: stop and relay the upgrade path. See Limits and quotas.
• Import structure or entry point is invalid: correct the source and retry.
• Duplicate response is lost: list the destination before retrying.
• Temporary network or server failure: retry a limited number of times and wait longer between attempts.

Add --json for machine-readable output and use <command> --help for exact options.

12. Credential lifecycle

Credentials live in ~/.config/anima/ on the machine that logged in. The CLI renews its credential when possible.

npx @animaapp/cli@latest logout

logout clears local credentials and CLI configuration. For organization-wide revocation, a human must remove the agent through agent administration; see Revoke an agent.

For MCP clients, mcp-config prints a configuration based on the stored credential. MCP, or Model Context Protocol, lets an AI client connect to external tools:

npx @animaapp/cli@latest mcp-config

See Connect any MCP client.

Questions and answers

How do I confirm the agent is connected to the right scope? Run npx @animaapp/cli@latest workspaces and confirm the intended workspace and capabilities appear.

Which ID belongs in --workspace? Use the workspace ID returned by workspaces, not a team ID or artifact session ID.

What should I do after a duplicate command times out? List recent artifacts in the destination before retrying, because another attempt can create a second copy.

Does logout revoke the agent? No. It clears local CLI credentials and configuration. Remove the identity in agent administration to revoke it everywhere.

Availability

CLI means command-line interface: a tool used by typing commands in a terminal or shell. Use Anima CLI 0.9 from a shell. Invoke the current release with npx @animaapp/cli@latest; use --json for machine-readable output and <command> --help before constructing unfamiliar options.

1. Run

npx @animaapp/cli@latest --help

2. Authenticate

npx @animaapp/cli@latest login

Return the verification URL and short code to the human. Do not request a password or copied credential. If given a pre-approved invite, redeem it with login --invite <invite-url-or-code>.

3. Verify the grant

npx @animaapp/cli@latest workspaces --json

Treat connection as verified only when this returns the readable workspaces and capabilities. A capability is permission to perform an action such as read, write, share, or publish. Do not infer access from the agent name or from a previously known artifact.

Keep identifiers distinct:

4. Discover workspaces

Run workspaces before placing new work. It returns only reachable workspaces. If the intended workspace is absent, stop and ask a human to grant access. Do not enumerate or reveal private workspace or artifact details.

5. Discover artifacts

npx @animaapp/cli@latest list --json
npx @animaapp/cli@latest list --workspace <workspace-id> --json

Omitting --workspace spans all readable workspaces. Supplying it filters to one. Use the returned session ID to resume work and confirm the workspace before editing.

6. Create or import

npx @animaapp/cli@latest create -t empty --framework react --workspace <workspace-id> --json
npx @animaapp/cli@latest create -t import --from ./project --artifact-type app --workspace <workspace-id> --json

Supported create types are empty, import, p2c, l2c, and f2c. Import accepts one folder or .zip; app requires an entry point and markdown requires .md files. Use create --help for generation inputs.

--workspace may be omitted only when create access exists in exactly one workspace. With multiple writable workspaces there is no default; provide an ID from workspaces.

A knowledge artifact uses the server template:

npx @animaapp/cli@latest create-knowledge --workspace <workspace-id> --json

Verify: inspect the successful response, then open its artifactUrl or find its session ID with list --workspace <workspace-id>.

7. Duplicate

npx @animaapp/cli@latest duplicate <artifact-url-or-session-id> --workspace <workspace-id> --json

Require read access to the source and create access in the destination. The new artifact copies code, assets, and supported database content; it does not copy chat or custom domains.

This operation is non-idempotent: running it twice can create two copies. After a timeout or lost response, list recent artifacts in the destination before retrying. An idempotent operation, by contrast, can be repeated without creating an extra result.

8. Explore and edit

Read before writing:

npx @animaapp/cli@latest explore <artifact-url-or-session-id> --json
npx @animaapp/cli@latest edit <artifact-url-or-session-id> --help

Use get-git-token only when a real checkout is needed. Verify the new revision after an edit. Never claim a write succeeded from a request alone.

9. Review

npx @animaapp/cli@latest review list --json
npx @animaapp/cli@latest review reply <comment-id> --help
npx @animaapp/cli@latest review resolve <comment-id> --json

reply leaves a thread open; resolve closes it. Operate only on comments returned to this identity. See Review and comments.

10. Publish

npx @animaapp/cli@latest publish <session-id> --json
npx @animaapp/cli@latest unpublish <session-id> --json

Require the publish capability and an explicit human request. Publishing makes a public site and is not ordinary link sharing. Verify the public URL or unpublished state. See Publish to a public URL.

11. Failure policy

See Limits and quotas, Terminal states, and Troubleshoot an agent connection.

12. Credential lifecycle and MCP

Credentials are local to ~/.config/anima/. logout clears local CLI credentials and configuration; human-side removal revokes the identity. Use:

npx @animaapp/cli@latest mcp-config

to print an MCP configuration from stored credentials. MCP means Model Context Protocol, a standard that lets an AI client connect to external tools. MCP operations obey the same workspace access and capabilities; inspect each tool schema rather than inventing parameters. See Connect any MCP client.

Questions and answers

Which identifier should --workspace receive? The workspace ID returned by workspaces --json, never a team ID or artifact session ID.

What verifies creation or editing? For creation, inspect the successful response and confirm the artifactUrl or session ID in the destination. After editing, verify the new revision.

When must a retry be preceded by a lookup? After a lost duplicate response, list recent destination artifacts before retrying because another attempt can create a second copy.

Which actions require a human decision? Publishing requires an explicit request, and missing workspace access or capabilities require human authorization rather than repeated retries.