The lycana command lets you, a script, or an AI agent read and change your Lycana diagrams. It offers the same abilities as Lycana's MCP server.

InstallCopy Anchor Link

It needs Node 20 or later.

npm install -g lycana

Standalone binaries for macOS, Linux, and Windows, which need no Node, are attached to each cli-v* release on GitHub.

lycana --help explains every command, the edit format, proposals, conflicts, and exit codes. It is written so that an agent can work from it alone, so an agent can learn the tool by running it.

Sign inCopy Anchor Link

lycana login

lycana login takes these options:

Where the key is keptCopy Anchor Link

Signing in saves a key in the macOS Keychain, the Secret Service on Linux (secret-tool), or the Windows Credential Manager. Without one, it goes to ~/.config/lycana/credentials.json, which only you can read. Keys are kept per API, so --api https://api-dev.lycana.ai and production keep separate keys.

Sign in with an agent keyCopy Anchor Link

On a machine without a browser, create an agent key in Settings → Connected agents (see Agent keys) and pipe it in. A key is never accepted as a command-line argument.

lycana login --with-key < key.txt

You can also set LYCANA_AGENT_KEY. It takes precedence over a stored key.

Sign outCopy Anchor Link

lycana logout removes this connection in Lycana, which rejects its pending proposals and stops its key working, then deletes the key on this machine. If Lycana can't be reached, the key is still deleted, and the link to Connected agents is printed so you can remove it there.

CommandsCopy Anchor Link

Signing inCopy Anchor Link

Organizations and projectsCopy Anchor Link

DiagramsCopy Anchor Link

Run lycana <command> --help for a command's details.

Options for every commandCopy Anchor Link

With --json, errors are printed on standard error as {"error": {"code", "message", "hint"}}.

Environment and linked directoriesCopy Anchor Link

lycana link saves an organization, and optionally a project and a diagram (--diagram <id>), for the current directory. It writes .lycana/config.json (the API and the ids, nothing secret) and adds .lycana to .gitignore. Commands run in that directory, or below it, then use them, and get and edit use the linked diagram when no id is given.

Organization and project are chosen in this order: the option, then the environment, then a linked directory, then the lycana switch default.

Change a diagramCopy Anchor Link

lycana edit reads a JSON list of operations from a file, or from standard input with - or a pipe. Read the diagram first to get its version and the ids of its objects:

lycana get <diagram id> --json

Then send the operations, with the version you read as expectedVersion:

lycana edit <diagram id> - --json <<'EOF'
{"expectedVersion": 7, "operations": [
  {"op": "create_node", "tempId": "cache", "name": "Redis", "service": "redis.redis"},
  {"op": "create_link", "from": "<api node id>", "to": "cache", "label": "reads"}
]}
EOF

Operations run in order, all or none, at most 50 in one edit. A tempId names a new object for later operations in the same edit, and the result maps it to the real id. A plain list of operations works too: then the diagram is read first and its current version is edited. --canvas <id> edits a subcanvas, and expectedVersion is then that canvas's version.

lycana help operations lists every operation and its fields.

Map a codebaseCopy Anchor Link

Put the systems on the top-level canvas, give each a subcanvas with create_subcanvas, and fill that with its services or folders, then their files. Write each node with upsert_node and its source, the path it describes, and each link with upsert_link. Running the same mapping again then updates the nodes and links instead of duplicating them.

Proposals and reviewCopy Anchor Link

Depending on the connection's setting, an edit applies at once or becomes a proposal that the user accepts or rejects in Lycana. lycana get <id> --json says which: changes is apply or propose.

For a proposal, edit waits about 50 seconds for the answer. If it is still waiting, follow it with lycana proposal <proposal id>, which waits again. Pass --no-wait to either command to return at once.

--review sends an edit to the user as a proposal even when the connection could apply it. Use it for changes the user would want to check first: restructuring or replacing large parts of a diagram, removing or renaming what they drew, or guesses about their system. It isn't meant for routine additions, and when the connection proposes changes, every edit is a proposal already. See Propose and Full access.

--request-id <uuid> makes a retried edit apply at most once.

Exit codesCopy Anchor Link

On a free account, creating a second diagram, or editing a personal diagram other than the one that can change, fails with exit code 1 and the code upgrade_required. The message names the diagram that can change and Lycana Pro's price.